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Interact Collaborate. It's highest-quality multi-point 
video conferencing and true real-time multimedia 
collaboration. It's all done in software. Any number 
of users. Over any distance. At any time. In real time. 
It flies, you don't 


* Actual video latency varies with bandwidth. 
In most cases, TeraMedia* latency b below 
the thmshofcl of human perception. 
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A WORD FROM 
THE PUBLISHER 


Wow. 200 issues! 

Two ... Hundred ... Issues. In this era of 
GHz, Terabytes, and microns, 200 seems like a 
pretty ho-hum number. In reality, it's pretty 
amazing. 

Those 200 issues include thousands of 
articles, many thousand pieces of news 
coverage, countless product reviews, editorials, 
and conference reports. It includes the essence 
and body of a community. 

And all of that happened through Apple's 
ups and downs. Through dot corns and dot 
bombs. Through growing economies and 
faltering ones. And yes, even through wars and 
terrorist acts. 

Today, thanks to you and the rest of the 
community, MacTech not only has the strongest 
readership it ever has, but also the strongest 
group of contributors, and writers. And, because 
this community is so influential, so core to the 
overall community, more companies want to get 
to MacTech readers through advertising and 
news than ever before. 

And over the past several years, we've grown 
beyond just MacTech Magazine but today have the 
nearly 10,000 page MacTech web site, the MacTech 
CD-ROM, MacTech Central at trade shows and 
conferences around the world, the Mac 
Programming Tutorial, MacTechJobs.com, MacTech 
News (through MacDev-1 and NetProLive), 

So, our promise to you is that while 2001 has 
clearly been MacTech's best year ever in every 
measurable way, we're looking for 2002 to be 
even better. 

That means that we’ll be continuing and 
increasing our new technologies coverage - Mac 
OS X, Quartz, Darwin, Gaming, Networking, 
and the list goes on and on. 

What can you do to help? Several things. 

First, write us at letters@mactech.com and 
tell us what you think. Want to gel up on your 
soap box? That's the place. 


Second, if you are an expert in a particular 
area, and think that would be useful to techies 
in the Mac community, write us a note at 
editorial@mactech.com and let's talk about you 
writing an article. 

Third, make your systems dance by creating 
great software and solutions, and dazzling the 
world with your magic. Check out all the great 
tools that are available to you in the community. 
After all, if you can use something off the shelf 
to help you get the job done that gives you that 
much more time for what you love. 

As many of you know, I've been in the 
Macintosh technical community since 1984. And, 
in January 1992, with a team of help, we took 
over the magazine and nursed it back to health. 

This January 11th, I will have been at the 
helm of MacTech for 10 years. I couldn’t have 
done that without a lot of help from a lot of 
people. Certainly, there are the obvious ones. 
Jessica Stubblefield, our Managing Editor has 
done a tremendous job of herding the cats we call 
authors and contributing editors. All of the staff at 
Xplain Corporation play a pivotal role (from our 
President to our customer service folks). All of 
our authors, contributing editors, advisors, and 
more. Our printer, Publisher's Press. 

And, of course you, our readers ... and our 
advertisers. 

There are too many people to thank 
individually here ... but we do thank you all, 
and look forward to traveling through the next 
200 issues with you. 

All the best this holiday season. And, may be 
worst of 2002 lie the best of 2001 for you and yours. 


Neil Ticktin 
Publisher 
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I only share my 
files with those 
I trust. 

I trust DAVE. 



Mac to PC, PC to Mac. Cross-platform 
file and print sharing is too vital 
to your business to risk. Trust 
Thursby, the company with 15 years 
experience. Trust DAVE, the solution 
with a proven track record. Share 
files and printers across a network 
with no barriers. DAVE installs on 
your Mac with no additional software 
required for the PC. It r s fast, secure 
and easy to use. Download a free 
evaluation today! 



www.thursby.com 


Mac is a trademark of Apple- Computer, inr, registered in the LAS- 
and othei counules. The Built for Mac OS X" graph E c is a trademark 
of Apple Computer, Inc. r used under license 

DAVE is a registered trademark of Thursby Software Syr terns, Inc. 

® -2002, Thursby Software Systems, Inc. 








MAC OS X 


By Andrew Stone 


Cocoamotion 


Getting more for less with Cocoa. 


Ever since ( 89 IVe been developing with the precursor to 
Cocoa, NeXTStep & GpenStep. In each release, new features and 
new concepts have been added to Lite Application and related 
frameworks, making life even easier for the third party 
developer. The more reusable software components that Apple 
provides, the less code 1 have to write and maintain. Imagine 
being able to remove more arid more code from your 
applications! Today I removed hundreds of lines of code in my 
Image drawing class by using the new NSImage drawing 
methods which respect the current transformation matrix. 

This article goes over a few ways to eradicate code that you 
may have accrued by using new objects and new feat it res in the 
old ones. We ll look at a simplified Image drawing object, the 
NSStepper, and the fairly new drag methods in N SO u dine View 
and NSTableView. 

NSImage Gets An Upgrade 
T ransformations 

Before Mac OS X 10.0, NSImage would draw ignoring the 
current transformation matrix. Now this is fine if you have a 
simple list of graphics - but if you have nested layers of scaled, 
rotated, skewed groups, it’s a royal pain in the patooli to 
micromanage image drawing based on depth of a hierarchy! 

For compatibility with older applications, the existing 
NSImage drawing methods such as compositeToPoint: a I way 
draw with only the origin of the image transformed. The image 
itself is drawn ignoring scale and rotation transforms with the 
origin at the low r er left While it has been possible to draw w ith 
the current transform by gelling one of the images 
representation and calling it’s draw r method, two new methods 
have been added to NSImage that do this for you. 

(void)drawAtPoint:(NSPoint)point fromRect:(NSRect)fromRect 
operation:(NSCompositingOperation)op fraction:(float)delta: 

(void)drawInReet;(USRect)rent fromRect:(NSRect)fromRect 
operation:(NSCompositingOperation)op fraction:(float)delta: 


If you pass in NSZeroRect for die fromRect: parameter, then 
the whole image is used. For drawInRect:, the image will be 
scaled to fit in the destination rectangle as well as transformed 
with the context’s current transform. Please note that if you use 
these routines in a flipped view, you will need to undo’ the 
negative y scale factor and adjust the origin before calling the 
new methods; 

// make a new transform: 

NSAffineTransform *t - [fJSAff ineTraitsf bra 

transform]; 

// by sealing Y negatively, we effectively flip the image: 

[t sealeXByil.G yRy'.-l.Q]; 

if but we also have to translate it back by its height: 

[t trsnslateXBy:0*D yEy; .bounds,size.height]; 

// apply the transform 

[t concat]; 

Now you can have groups of images that are scaled and 
skewed, and these transformations w ill automatically be correctly 
applied to the image when it is rendered. Total lines of code: 5, 
Number of lines of code replaced: 250, Improvement of rendering 
speed: 2x, Reliability and correctness were improved greatly. 

Transparency: 

Using these new methods, you can add a slider to your 
interface which controls the transparency of the image, because 
the new methods take a fractional dissolve, from 0.0 fully 
transparent to TO fully opaque* Let's say you store the amount of 
transparency as a float in ^dissolve - then your call to render the 
image would be: 

// \vt j have translated already m the origin of Uic image in its current group 
// .dissolve varies from 0 for no dissolve no 1 for fully transparent: 

[image 

drawInRect:NSMakeRect( 0 . 0 , 0 . 0 a _bounds.size,width, bounds.size.he 
ight) fromRect:NSZeroRect operation:NSCompositeSourceOver 
fractlon: 1.0 _dissolve]; 


Andrew Stone <andrew®stone.com> is the chief executive haquer at Stone Design Corp <http://www.stone,coni/> and divides his lime between 
raising children, llamas cane and writing applications for Mac OS X. 
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The # 1 Best-Selling Croup 
Scheduler and Contact Manger 
for the Macintosh! 

You're a busy person. You've got things to 
do, people to see , and a seemingly infinite list 
of things to keep track of. Whether it r s just 
yourself or a department at a Fortune® 500 
company, you (and everyone that works with 
you) need to be organized. Maybe you've 
tried other ways: paper planners , lots of 
sticky notes, other software. But now you 
can't afford to waste any more time or 
effort. You need a serious solution. One 
that's so easy to use that you can get 
started right out of the box. One that will 
grow with you , One that has the features 
and capabilities you need. 


Now Up-to-Date & Contact is the internet-sawy 
contact manager. With a click of the mouse, you 
will be soaring through cyberspace. Want to 
publish your calendar on the web, or get a map 
to a meeting, or even find the restaurant near¬ 
est to an important client? It's all a snap with 
Now Up-to-Date & Contact! Additional features 
you'll rave about include: built-in word processing with 
mail merge, auto-mated fax creation, integration with your 
favorite email software, advanced Palm synchronization, and the amazing 
new Grab-'n-Go ™ that allows you to instantly grab information from virtually any 
source and have Now Up-to-Date & Contact create any necessary follow-up reminders ♦ 
Now Up-to-Date & Contact even understands English commands so you can schedule 
appointments without touching the keyboard.* 


With its amazing power and phenomenal speed, combined with unparalleled ease of use, 
it is no wonder that Now Up-to-Date & Contact has won the coveted Eddy Award for best 
information Manager, seven World Class Awards, and a host of rave reviews , Now, with 
Version 4.1, Now Up-to-Date & Contact adds full support for Mac OS X, making it the 
indispensable product for people who want to be organized , 
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PDF Optimization: 

In 10,1 and earlier, there is an “over-optimization"* bug in 
Apple's implementation of the NSPDFlmageRep whereby it 
draws from its bitmap cache in certain circumstances which are 
incorrect. For example, when you print, you want the full 
resolution PDF, not a standin bitmap image which will produce 
jaggies. Also, when you zoom in, you want the PDF to render 
beautifully at that scale. You might want to test if you are 
printing or saving or at a high level zoom, and render the image 
directly from the PDF data: 

// If image is a pdf, and we am printing or saving or need the actual data: 

if (needTQUseRealFDFData) I 

// grab the image's best representation, the actual NSPDFlmageRep 
NSPDFlmageRep *rep “ Linage 
bestRepresentationForDevice;nil]: 

// ask it to draw within our bounds: 

[rep 

drawInRect;N5MakeRect[0.0,0,0 abounds,size.width,.bounds.size,h 
eight]]: 

) else 

[image 

drawinRect :NSMakeRect(0,0,0.0 ..hounds.size,width,.bounds, 3 ize,h 
eight) fromRect:NSZeroRact operationiNSCotnpositeSourceOver 
fraction:!.0 - .dissolve]: 

The trick to get zoomed PDF to render onscreen at full 
quality is to multiply the size of the PDF image to the zoom: 

// helper method to return an integral size of an image, based on the zoom: 

- (NS5ize)sizeForZo6m:(Float]zoom I 
NSSize s = Lim&ge size] ; 
if [zoom == 1,0 ]| zoom —* 0,0) return s; 

// images cannot be fractional sizes, so we round down: 

return NSMakeSize(Floor[s.width * zoom), floor(s,height 
* zoom)): 


// Before drawing the image, wc check if we are zoomed: 

// if our image is a PDF, and we re drawing to screen, get a bigger image: 

if (.isPDF ftk [[NSGraphicsGontext 
currentContext] IsDrawlngToScreen] && zoora I- 1,0) ! 

NSSize & = [self sizelor2oom:zoomj: 
if CzootnedPDFImage = nil) I 
.zoomedPDF Image - [_image 
copyWithZone:[self zone]]: 

} 

if ( 1NSEqualSizes([.zoomedPCFImage size], s}) 
t_zOomedPDFImage setSize:s]; 
image “ .zoomedPDFImage: 

] else I 

image = image: 

I 


NSStepper 

An NSStepper provides what is known in Carbon as little 
arrows’. These are common controls for date and time entries, 
but are also useful for any Ul component that has values which 
can be “tweaked” a little bit. For example, we use them in Create 
to allow small adjustments to scale: 


*™Q ioo 

The Utile arrows' are a new addition to Cocoa t but have heett 
around Carbon for awhile . 

Like most control subclasses, NSStepper relies on the 
behavior of its custom NSStepperCeH for its functionality. You 
don’t even need to know to this to use the stepper because the 
control has cover methods for the standard cell methods. Besides 
methods familiar from slider controls (setMaxValue:, 
setMinValue:, setAutorepeat:), the NSStepper allows you to set 
the granularity of an increment (or a decrement if the lower 
arrow is clicked) with setlncrement:. 

You can also set whether the values loop around (as would 
be true in the case of rotation stepper) or not with 
setValueWraps:. In the example of a scale slider, for example, it 
makes no sense to go from the maximum value to the minimum 
value with one dick! 

Using tiie NSStepper in your interface consists of two parts: 
initializing the stepper for your requirements and keeping the 
value of the stepper in synch with data model since it needs to 
know the original value in order to increment or decrement the 
value. You can initialize the stepper when loading the Ul 
components for the first ilme or directly in Interface Builder, This 
example is for a rotational slider: When loading the Ul 
components the first time, you might initialize the values of the 
stepper, in this example, for a rotational slider You can also set 
these values directly in Interface Builder, or programmatically in 
the File Owner’s class in awakeFromNib, which is called by the 
nib loading mechanism if this method exists: 

(voi d) awakeFroaiNib [ 

[stepper setMinValue:0.0]; 

[stepper setMaxValue:360,D]: 

[stepper setIncrement:1.0] : 

[stepper setValueWraps:YES] : 

[stepper setAutorepeat:YES]: 
if target/action set in IB 

I 

When inspecting a graphic that can be rotated, you reload 
the stepper w r ith the current value of die graphic’s rotation: 

double currejitRatation “ [graphic rotation] : 

[circularSlider setDoubleValue: currentRotation]; 
[rotationStepper setDoubleValue: currentRotation]: 

The stepper handles all mousedowns and it knows whether 
it needs to increment or decrement the value. Let's say you have 
connected the stepper to an action “incrementDecrementAction:'': 
The stepper has set its internal value to its incremented or 
decremented value, depending where Lhe user clicked. 

- (void)incrementDecrementAction:(id)aStepper f 
[self setSomeValue:[aStepper doubleValue]]: 

// take the value from the stepper 
[self reioadlnspectingUI]; 

ff update textfiekk, sliders, etc with new values 

) 
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Top 10 Reasons 
Why You Should Buy 
Frame! Web® 


10. It’s the most accurate Web site visitor analysis tool available 

9. Everyone should own at least one product named after the 
world’s deadliest spider 

8. One of the developers once worked in the gear room of the 
world’s highest aerial tram 

7. Buy the product and we’ll let you keep the CD 

6. It produces reports so beautiful you’ll want to carry them 
around in your wallet 

5. It runs on Mac, Linux, Windows, FreeBSD and Solaris 

4. Someone needed to start a new trend 

3. Thousands of your colleagues are already using it 

2. It’s 400% faster than competing products* 

And the #1 reason why you should try Funnel Web Analyzer is... 


(What, you think we’re going to give it up on the first date? 
Go to www.quest.com/to pi 0 to find out!) 


‘Refers to a recent independent review from Neiger Computer Consulting. 


QUEST 
SOFTWARE 

www.quest.com 




United States 1.949.754.8000 * Germany +49.221.5694.111 ■ United Kingdom +44.1628.601000 • France +33.1.4131 ..96.96 * Australia +61.3.9811.8000 


The NSStepper is an excellent addition to the Cocoa 
developer s Uxdkil, and both saves some lines of code as well as 
provide a standard mechanism for tweaking U1 values. 

Drag & Drop Support in NSTabj^View and NSOutuneView 

The refinement of the Application framework is art ongoing 
process. For example, a few years ago we had to write our ow n code 
for drag and drop row r reordering of table views and outlineviews 
(http://vww.stone.corn/GIFfun/GIFfunSource/Row_Moving_ProtocoLhtml). Now, 
tliat code can l^e thrown away, and you can use the exposed .API to 
accomplish this: 

typedef emim I. WSTablsViewDropOn. NSTableViewIiuopAbove J 
NS Table ViewD ro pQpe r ation; 

// In dra# and drop, used to specif a drop Operation, For example, given a table with N 
rows (numbered with row 0 at the top visually), a row of N-l and operation of 
NSTaNeViewDrqpQn would specify a drop on die last row.To specify a drop below the last 
row, one would use a row of N and NSTableMewHiopAbove for the operation, 

■ {B00L]tableView:(NSTableView *)tv writsRows:(MSArray*]rows 
toPaareboard:{NSPasteboard*)pboard: 

//This method Is called after it has beca determined that a drag should begin, but before 
the drag has been started. To refuse die drag, return NO, 'lb start a drag, return YES and 
place the drag data onto the pasteboard (data, owner;etc...). The drag image Lind other drag 
related information will he set up and provided by the table view once this call returns with 
YES. The rows array is die list of row numbers that will lie participating in the drag 

(NSBragOperation)tableView:[NSTableView*]tv validateDrop;(id 
OTSDragginglnfo>)info proposedRow:(int)row 
p i o po£> e dD ra pO pe r a t ion: (US Ta b 1 e V i ewD r opQp er at ion) op; 

//This method is used by NSTableView to determine it valid drop target. Based on the 
mouse position, the table view will suggest a proposed drop location. This method must 
return a value that indicates which dragging operation die data source will perform, Ihe 
data source may “re-target "a drop if desired by calling setDmpRowdropOperation: and 
returning something other t han NSDngOperaiionNone. One may choose to re-target for 
various reasons (eg. for belter visual feedback when inserting into a sorted position) 

- (BOOL) tab 1eVlew:(NSTa b1e Vi ew*)tv ac eeptDrop:(id 
(NSDragginglnf g> ) info row : {int}row 
dropOperation: (NSTableViewDropOperation) op: 

//This method is called when the mouse is released over an outline view liiat previously 
decided to allow a drop via the validateDrop method. The data Source should incorporate 
the data from the dragging pastelHiiud at this time 

Our free application, GIFfun, allows users to reorder the 
individual images that make up the final animated GIF. 1 fare 1 s a 
sample implementation of the Drag and Drop .support in an 
NSIabkView: 

static int _moyeRow - 0; 

(BOOL)table'View:(NSTableView *}tv writeRows:(NSArray*)rows 
toPasteboa rd:( NSPa at aboa rd *) pboard 

int count = [gifFileArray count] ; 
int rowCount - [rows count]; 
if (count ( 2) return W0: 

[pboard declareTypes:[WSArray 
arrayWithObject:GifInfoPasteEoard] owner:self]: 

|pb oa rd set P rope rtyLi s t:rows forTyp e:Gif InfoPast eBoard]; 
inoveRow = [[tows obj ectAt Index :0] int Value] ; 
return YES; 


(unsigned int) tableView:(NSTableView*) tv validateDrop: (id 
<N3DraggingInfo>)info proposedRow;(int)row 
proposedliropOperation:(NSTableViewDropQperation)op 

I 

if (row != _moveRow} S 

if (op=NSTa b leVi ewD ropAbovej [ 
rBturn US DragOpe r ationAI1: 

] 

return NSDragOperationNone; 

I 

return NSDragOperationUone: 


) 

- (BOOL)tableView:(NSTableView*)tv acceptDrop:(id 
(NSDragginglnfo>)info row;(int}row 
dropOperation:{NSTableViewDropOperation)op 
[ 

EQ0L result - [self tableView:tableView didDepositRow:_moveRow 
at:(int)row]; 

[tableView reloadbata]; 

return result: 

J 

// here wc actually do the management of the data model: 

(BOOL)tableView:(NSTableView *)tv didDepositRow:(int)rowToMove 
at:(int]newPosition 
[ 

if (rowToMove 1 £<& newPosition 1= 1) t 

id object = [gifFileArray objectAtIndex:rowToMove]; 

if (newPosition < [gifFileArray count] - 1) \ 

[gifFileArray removeObj ectAtIndex;rowToMove]; 

[gifFileArray inaertObject:object atlndex:newFasition]; 

} else [ 

[gifFileArray removeOhjeetAtIndex:rowToMove]; 

[gifFileArray addObject:object]: 

I 

return YES: // ie reload 

I 

return NO; 

I 

These few lines listed replace the 650 lines of code from 
SDTableViewJi, SDTabieView.m and 5f)MovingRowsProtocol.il. 
The complete source code to GIFfun is available at 
http://www.stone.com/GIFfun/. 

Adding Features By Doing Nothing 

And, if my Zen slacker coding model isn't convincing enough, 
consider how you can add new features by doing nothing! 

If you are using the Modd-View-Controller pattern and taking 
advantage of the NSDocument architecture, then t he introduction of 
Mac QS X 10.1 brought you new features, without you doing 
anything. Because your application links at runtime with the current 
version of the Application and Foundation frameworks, new 
features available in l lie kits become available to your users. 

10 J adds Hidden file extensions (which is way more Mac-like 
than the UNIX file extensions), ability to track documents, folders, 
and volumes which are renamed, and ability to save documents in 
a way which preserves aliases to the documents and additional 
document info such as maintaining file permissions, creation date, 
and icon settings. 

Some of these features do require that you recompile your 
application, because die Apple engineers wanted to provide full 
backwards binary compatibility in programs tint were linked against 
the Mac OS 10.0 version of die Cocoa framework. 

Conclusion 

Software is a process not a product, and therefore it is never 
finished! The frameworks that Cocoa developers rely on are 
continually being refined and improved, so it s very 
important to carefully read the Release Notes found in 
/l)eveIc>per/I)< jcuincntntk>n/ReleaseNotes, espedaIly A ppKit. h tin 1 
and Foundation.htinl. Always check for new functionality which 
can replace your home-rolled versions, thus making your 
application more compact and reducing the code base that you 
need to .support, HD 
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COVER STORY 


By G.D. Warner 


Error Messages: 

The Good, The Bad, And The Ugly 


Writing Error Messages That Don't Make 
Your Users Feel Stupid 

41 You are in error You are a biological unit. You are imperfect , 11 

As error messages go, that quote from the original Star Trek 
episode, “The Changeling" is — well, actually kindu scary, 
considering what happened in that episode (Nomad, remember? 
A small robot that destroyed planets for fun — because that 
planet's inhabitants were, in Nomad/s "eyes," imperfect). 

While I'm sure RB developers don't write error messages 
like that — and, coupled with REAL Software's failure to insert 
a "Smite" command into the IDE makes carrying out the 
implied threat difficult, at best — I wanted to take this 
opportunity to run through, as the title says, The Good, The 
Bad, and The Ugly’ of error messages. 

The British magazine, MacFormat (which some would say 
is the British version of Mac Addict, though in fact the reverse is 
true) has a section devoted to bad error messages, entitled "Silly 
Things Your Mac Says/ Alas, MacFormaf s web presence 
(http;//www.macformatxo,uk) is not quite as strong as that of 
MacAddicfs (http;//www,macaddictxom) ? so I’m afraid 1 can't refer 
you to a page to view them all Sony abut that! 

(Initiate Twilight Zone mode: que creepy music , Dim Rod 
Setting voice as True: ) 

Consider, if you will, the typical new computer user. S/he 
has just enrolled in the Computers For Dummies class at her 
local community college — using Windows W (pronounced 
"uh-oh," in case you were wondering) as the Training Platform 
of Choice. Everything goes well in the class that first week 
(remember, we're using our imaginations, here), and our new 
computer user finishes that first week, and goes out and buys 
her own computer. 

And gets her first error message. The horror begins 
(see Figure 1), 



Figure L Thanks a Lot (End Twilight Zone mode). 

Alan Cooper, in his book About Face: The Essentials of User 
Interface Design, writes: "This is what all error messages feel like 
to users... No matter how nicely your error messages are 
worded, this is how they will be interpreted/ 

But what makes a good error message? 

The Microsoft Manual of Style, Second Edition, provides 
pointers for writing error messages: 

"When you write error messages, use the passive voice to 
describe the error, and, if necessary, the third person (refer to 
l he computer' or l the program’). You can also blame the 
product. Addressing the user directly as ‘you' may imply that 
the user caused the problem. Try to make error messages 
friendly, direct, and helpful,” 

Apple's Aqua Human Interface Guidelines tells us: 

“A good alert message states dearly what caused the alert to 
appear and what the user can do alxiut it. Express everything in 
the user’s vocabulary/ 

This is good advice ,,, but Alan Cooper says it a bit better: 

"Don’t make the user look stupid/ 

Mr. Cooper later provides another interesting example of 
how error messages shouldn't be written, reproduced here as 

Figure 2: 


G.D. Warner is a technical writer, a Web-Dev Ninja-tn-Training, and resides in Seattle, where die Shadow of Redmond looms long and large. 
He can lie reached at gdwarntT@niac.com. 
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Figure 2, What the —!? 


What would go through your mind if the above error 
message were to show up on your screen? Probably something 
similar to what Mr. Cooper wrote: 

“Thank you so much for sharing that pithy observation 
with us. Why didn’t you notify the library? What did you 
want to notify it about? Why are you telling me? What do I 
care? Maybe you’d like to comment on what Pm wearing, 
too? And besides, what am 1 OK’ing? It is not OK with me 
that this failure occurred!” 

Couldn’t have said it better myself. 

To reiterate Apple’s recommendations: 

* Tell the user what happened 

* Tell the user how to fix whatever is wrong 

* Tell the user what happened in their own vocabulary 

This last one is particularly important: if your error message 
says something like TmtSvrErr in Serial/USB port,” your user is 
most likely going to be confused by “PrntSvrErr.” Why not 
simply w rite “Printer Server Error,” if indeed that’s what it means? 

The Good 

There aren't a lot of good examples out there.., but 1 did 
find a few that come close. Take Figure 3 for example: 



Figure 3* Example of a Good Error message. 

This error message follows the basic guidelines of a good 
error message: 

It tells the user what’s wrong (more or less) 

It offers a fix 

It delivers its message in plain language 



Fetch 4.0 


Off the Leash 



Fetchsoftworks.com 

New Version • New Company 
Same Author 
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Figure 4 T from Apple's Aqua Human Interface 
Guidelines gets the job done: 


The document “Trip Request 1 ' could not be 
saved because the disk “Work Stuff 1 is full. 

Try deleting documents from 'Work Stuff or saving 
the document on another disk. 

' Cancel * f OK x 


mmmmmrnmtmmmmmmmmmmmmmrnmm 

Figure 4 Another Good Error Message. 

Figure % Another Good Error Message. 




It tells the user what's wrong — and why 
It offers not one, but two possible Fixes 
It delivers its message in plain language 

The error message shown in Figure 5 seems to have 
done it correctly: 


Study bugs? 



Or KILL them? 



New Version 

Upgrade Now $29 
www.onyxtech.com 

Detect stele handles t runtime block overwrites, 
DisposeMandle on resources, Invalid BlockMoves , 
writes to location zero , Validate Handle/Pointer 


* It tells the user what's wrong — and why 

* It offers not one, not two, but three possible Fixes — and 
includes a phone number lor Tech Support 

* H delivers its message in plain language 

By all rights, this should be the best of the best — but 
my technical writer instincts tell me it’s far too wordy, A user 
faced with this error message would most likely not bother 
to read it (“Too much information, too much information!”), 
then just click OK. 

The Rad 

Ifs far easier to find examples of bad error messages than 
good ones.., and a lot more fun! So here we go. 

Figure 6 is from an early version of Netscape: 



“Netscape: In Mac Nauiyalor 3.6, Jaua 
won't initialize” from “Unknown” is 
damaged and cannot be printed. 


i 


Figure 6. Bad Error Netscape Style* 

in his article “Why You Can't Run Java, 11 Mark Hurst 
said...well, basically he said that this error message might be 
difficult for most users to understand (yeah.,, that's it!). 

Another, shall we say, somewhat-less-than-useful error 
message is shown in Figure 7: 
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Awesome!” 


'The power, quality and feature set of 
Lasso Professional 5 is very impressive. 
The new documentation is definitely 
among the best in the business." 

Johan Sdfve; HaJmstad, Sweden 


"Blue World has managed to add an 
immense amount of functionality and 
scalability without sacrificing any of the 
ease-of-use of previous versions. New 
features like LassoApps, custom tags 
and LassoScnpt create a development 
environment that seems almost limitless." 

Tom Wrebe; Vancouver, Canada 


s* Lasso 

l Professionals 


in 


Quickly Bulk) ftiwW 

DataDr^nWtebAppIkntlom 


"With Lasso, I have been abfe to single- 
handedly develop sophisticated solutions 
for internal and external use in less time 
than I see teams of people take with 
other middleware languages." 

Greg Wiltits; Santa Ana , California 


"This new release, I have got to admit, 
is truly amazing, The rich array of new 
features, the brand new documentation 
and the amazing new administration 
interface make Lasso Professional S 
definitely worthy of a purchase." 

Brian Olsen; Brooklyn, New York 


Upgrade today to the most powerful Web application server for 
Macintosh and beyond and you'll discover why so many Web 
developers claim Lasso Professional 5 is the must-have tool for 
quickly building and serving powerful data-driven Web sites. 

Lasso Professional 5 introduces a next-generation, object-oriented 
Web programming language, advanced Web application server 
administration, an embedded Lasso MySQL™ high-performance 
database server, a new distributed architecture, new platform and 
data source support, unprecedented extensibility and customiza¬ 
tion, 1800 pages of rewritten documentation and over 200 new 
features and enhancements. Lasso Professional 5 provides vast new 
power and features while maintaining the legendary ease-of-use, 
performance, and reliability that make Lasso the preferred tool for 
tens of thousands of Web developers, ISPs, and IT/IS professionals. 



r~ i r' ~ir i 



Lasso Administration controls your entire setup via an 
attractive and intuitive Web browser interface. 



If you're serious about building and serving data-driven Web sites, 
but don't want to spend a serious amount of time getting it all to 
work, there's no better choice than Lasso Professional 5. 

Visit the Blue World Web site today and see how Lasso products can 
help you quickly build and serve powerful data-driven Web sites. 

Lasso - The Leading Web Tools for Macintosh and Beyond 



**•**'•**■ mii ►[ 


Lasso Database Browser provides instant access to all 
your databases, without writing a line of code, 


blueworld 

www* blueworld.com 


© 2001 Blue World Commumcatjores, Inc. MySQL is a trademark of MySQL AB. FileMaker Pro t-s S registered trademark of FileMaker, Inc, Lasso, Lasso Professional, LasSdAjOp, LassoSedpt 
and Blue World are tfadernarks of Blue World Corrirnunieatiora, Inc. All rights reserved 

























Figure 7 Really Bad Error Message. 


I wonder what happened here? — Oh, yeah. “Some sort of 
error.” Obviously. 

You've probably seen or heard about the e-mail that 
circulated some time back with error messages written in Haiku, 
the ancient Japanese form of poetry. For those of you who don't 
know (or dozed off a lot during the poetry section of your 
English classes), Haiku has only Lhree rules: 

Three lines only 

First and last lines are to be no more than three syllables 

Second line consists of no more than seven syllables 

Here’s one: 


Three things are certain: 

Death, taxes, and lost data. 

Guess which has occurred. 

Eve placed the URL in the Reference section so you can 
read the rest... but if you can't wait, fire up a computer 
running the BeOS, load up Re's web browser, Net Positive, 
and type in a URL without being connected to a network ... 
and see what you get. 

Hopefully, you'll get something like Figure 8: 



Uh-oh... I feel inspiration beating me about the head and 
shoulders! 

In NetPositive 
It is quite easy to find 
Poetic Errors 
(Sorry about that.) 


Someone who identifies himself as “Johnnie Favorite” or 
"Happy Mega Fighting Man,* and a former Be employee tells me 
this feature can be turned off in one of the NetPositive settings. 

I’ll get to that ... one of these days. 

Not to I^e outdone, a few Apple developers at Dantz have 
written a few of these (at least for early versions of the 
Retrospect manual) as shown in Figure 9 (thanks to 
ResExcdlence.com): 


□ 


Sorry, a Haiku error has occur ed... 
A file that big? 

It might be very useful. 
But now it is gone. 


Figure % Dantz Retrospect's Haiku Error Message , 


The Ugly 

Not a lot of screenshots for this category, as some of these 
are Unix/Linux error messages, passed on by Word of Mouth. 
My favorite: 

Printer on fire. See the Reference section for a link for more 
info on this one,., 

A dose second, from Linux fsck (the Linux version of 
“Scandisk"): 

"Either there is a hug in fsck or some honehead (you!) is 
checking a live filesystem , Please report hugs in fsck to <email 
address supplied >. IT 

Tacit' writes in comp.lang,basic.realbasic: 

Tor the worst error messages ever written by God or man, 
I suggest you take a look at Windows 2000. It has some error 
messages you absolutely will not believe. 

Attempt to propogate SUIDs across Active Directory failed 
with code 1602.’ 

“In English, this means: You have special permissions set 
for a user who does not exist/" 

Interesting ... 

This error message uses error codes. Opinions on these are 
mixed: Some like them, some hate them... but they do have 
their uses. 

Using that error code, a developer can track the number 
of times a particular error is displayed, compare it to other 
errors that report error codes, and from there decide which 
one to fix first. 

MT-NewsWutcher uses similar error codes in some of its 
error messages* as shown in Figure 10; 



Ait unexpected error occurred. 

The error code vas -280?. 



Figure 10. MT-NewsWatcher Error with Error Code. 
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And Lhen, of course, there’s these; 


Tool Tips, die Balloon Help on the Windows side of things, 
is also something one needs to be careful of* The tool tip shown 
in Figure 11 cost a developer his job: 


Cancel 

i 

Help 

i 




Dick this to display an overview of this dialog box, idiot. 

For Help on an itern^ click ? at the top of the dialog box, and 
then click the item. 


Figure 11 . One Way Ticket Out the Door for this developer 
Here’s an interesting one, from Free java: 

El 


Free Java 



Figure 12 , Let's Get Biblical 



Figure 13* Dude! (Welcome). 



Dude —I 


Of 


Figure 14. Dude—! (Okay). 



1 wonder if Free java has a ‘Smite 1 command..*? Hminmin 


Figure 15 Dude —/ (Toast). 
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While it is true that a skilled linguist could probably 
differentiate between “Dude—f as an expression of agreement, 
and “Dude—!” as a warning message, relying on this ability for 
your error messages is probably not a good idea ... so the less 
said about the “Dude” family of error messages, the better 
In fact, forget I mentioned it, okay? 

Okay. So What? 

Good question. How about this quote: 

“Nothing says more about what you think of your users 
than error messages.” 

This quote, from Scott Berkun’s article, “The Web Shouldn't 
be a Comedy of Errors,” really says it all If it doesn't "say it all’ 
to you, he follows up with a discussion of some excellent 
software engineering ideas on handling errors (see Scott Berkun 
in the Reference section ... and take another look at Figure 11), 
Like in one of the Karate Kid movies (“Kid? I’m thirty- 
five!”), when Mr. Miyagi describes the best way to black a punch 
by the "simple" method of “No be there when punch arrive,” 
Scott's article recommends designing your program so that it has 
fewer chances for your users to require an error message. 

Chuck Martin, a posting to the Tech Writer's list agrees, 
“...design, as much as possible, the interface so users can't make 
errors, or at least will have a more difficult time making errors.” 


StoneTable 

You thought it was just a replacement 
for the List Manager ? 

We lied, it is much more ! 

Tired of always adding just one more feature to your LDEF or 
table code ? What do you need in your table ? 

Pictures and Icons and Checkboxes ? 
adjustable columns or rows ? 

Titles for columns or rows ? 

In-line editing of cel! text ? 

More than 32K of data ? 

Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make it worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today ! 

Only $200.00 MasterCard & Visa accepted. 

StoneTable! Publishing 
More Info & demo Voice/FAX {503} 287-3424 

http ://www. teleport.com/-stack stack @ teleport.com 


For instance, a field that requires numerical input should 
screen out alphabetical characters, as illustrated in this code 
snippet (KeyDown event of an Edit Field): 

listing 1: ASCII On ly, Please_ _ _ 

ASCII Only, Please 

Disables Tiorr-numericaJ keystrokes in an edit field. 

Function KeyDcywn(Key As String) As Boolean 
If (ASCCkey) < 43) Or (ASC(key) >57) Then 
If (ASC(ksy) = 3) Or C(ASCtkey) >= 28) And (Asc [key) <= 31)) 
Then 

Return False 
Else 

Return True 
End If 
Else 

Return False 
End If 
End Function 

This kills the need for an error message that reads 
“Dumbkopfi Numbers ONLY in this field!" or something similar. 

Another thing lo consider (with some applications, 
anyway): disabling the Okay’ or ‘Submit' button until all 
required fields are filled in. This avoids the “You idiot! You 
forgot to type in your fax number!" error message — when your 
user doesn't have a fax number to enter, and simply hits the 
Okay button, thinking s/Ihe's Finished entering data. 

Robert Heath, another member of the Tech Writer's list (see 
the Reference section) says, “My own peeve is messages with 
exclamation points. ‘You must enter a date!,' etc. 

Wrapping Up 

In this article, we’ve taken a look at what makes a good 
error message, what makes a bad error message, touched on 
some 'ugly ? error messages, skimmed the surface of software 
design methodology, and dipped a metaphorical toe into the 
waters of user interface design. Hopefully, we've all teamed 
something along the way... but there's only one way to be sure! 
A quiz. Your question — for the grand prize of a bag of pre¬ 
cooked microwave popcorn, mailed to your house by our own 
managing editor. Jessica Stubblefield (First come, First served, no 
guarantees on how well cooked the popcorn will be): 

If your user is trying to print but can t, is it better to display 
an error message that reads — 

A. ' Failed to initialize printer port [OKI," 

B. ‘Having trouble printing. Ensure the printer is connected 
to your computer and that the power cord is securely connected 
and press the ‘Retry' button, (Retry! (Cancell” 

“Printer on fire! Get out now !! lOkayl” 

“DUDE!!! I Okay 1” 

If you answered A, congratulations! Your users will hate 
you, and you are well on your way to becoming as infamous as 
the person that wrote that immortal phrase, “Someone put us the 
bomb.” Or perhaps the other immortal phrase, “All your base are 
belong to us.” 

If you answered B. congratulations! Your users will love 
you, and actually pay for your shareware. 

if you answered C, congratulations! You're doomed to a 
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lifetime of answering the telephone support lines for the 
software you wrote, which caused the printer to catch fire in the 
first place* Your days will be long (15 hours!) and you’ll only get 
minimum wage — unlike your fellow tech support-folk, who 
support applications written by the guy whose error messages 
read like those in answer B These guys get more money 
because their developer gets paid for his software. 

If you answered D ... urn ... well, the less said about that 
the better! 

You re educated 
Put away this magazine 
And go code something. 

Heh. 
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DECLARING 

EXTERNAL 

FUNCTIONS 


By joe Strout 


Declaring External Functions in REALbasic 


Harness the power of toolbox calls without 
resorting to C 

Declaring Your Inteniions 

REALbasic's extensive library floats on top of the sea of low- 
level functions that comprise the operating system like a cruise ship, 
protecting you from the dangers that lurk below. This is a two-sided 
coin; it frees you to concentrate on what you want to accomplish, 
rather than the details of how it’s done on this or that platform, but 
it also places limits on what you can do, Wien you hit one of those 
limits, and need to accomplish something not directly supported by 
the REALbasic library, then you’re going to have to get wet. 

But even then, you have a choice. You could write a plug-in 
in C++, and link this plug-in into your REALbasic application 
[reference - Erik's article on plugin dev]. That gives you full power 
to do pretty much anything, but it also requires quite a bit of 
learning, especially for developers not already familiar with C++, 
The other option Ls to use the Declare statement, which makes a 
function in REALbasic that links to a function in die operating 
system or a shared library. IT is is done entirely within REALbasic; 
no C++ is involved. To extend the ocean analogy a just bit further: 
writing a plug-in is like diving into the ocean untethered, while 
using a Declare is like hanging onto a life preserver on a rope — 
there are still restrictions on what you can do, but it’s also a lot 
easier to avoid drowning. 

Though the Declare statement is used entirely within 
REALbasic, it's still an advanced Feature and a source of difficulty for 
many experienced REALbasic coders. This article will attempt to 
clarify and illustrate its use. After reading this article, you'll be able 
to declare calls to classic MacOS, Carbon, or Win32 system routines, 
as well as to other shared libraries. This gives you the power to do 
a wide range of tilings not otherwise possible in REALbasic. 

The Declare Statement: A Close Look 

With no further ado, let's jump right into an example. Listing 1 
shows a REALbasic function that toggles the "modified’ 1 flag of a 


window. (Under Mac OS X, this sets or clears the little dot in the red 
Close widget in the title bar.) Since the functions involved are only 
available in MacOS 8.5 and higher, ii also checks the system version 
before attempting to call them* 


Listing 1: ToggleModified 


foggteModified 

Toggle the “Modified’flag of the given REALbasic window. This subroutine requires MacOS 
8,5 or higher, and does nothing under older versions of MaeOS. Il will not compile as-is for 
68k (these functions ire not available to 68k apps). 

Sub ToggleModified(win As Window) 

//Toggle the given window's Modified fl:ig 
Dim sysVersion. err As Integer 

If TargetCarbon 

Declare Function IsWindowModified Lib “CarbcjnLib" (window 
as WindowPtr) as Boolean 

Declare Function SetWindowModified Lib "CarbonLib* (window 
as WindowPtr. modified as Boolean) as Integer 

frelse 

Declare Function IsWindowModified Lib M Windowslib' , (window 
as WindowPtr) as Boolean 

Declare Function SetWindowModified Lib "WindowsLib" (window 
as WindowPtr* modified as Boolean) as Integer 
#endif 

// check the system version, since these functions aie only available 
// in MacOS 8.5 .ind lii^hcr 

if System.Gestalt(“sysv’T syaVersion) and sysVersion >= 

&h0850 then 

// system version is OK, so do the toggle 

err = SetWindowModified(win, not IsWindowModified(win)) 
end if 
end if 
end Sub 


There are several things to notice in this example* First, if we 
want to compile for both “classic" Mac intosh and for Carbon, we 
need two versions of each Declare — one linking against 
CarbonLib, and the other agatast the appropriate toolbox library 
(often InterfaceLib, but WindowsLib in this case)* Next, built-in 
REALbasic functions generally do the right thing for any version of 
MacOS your code may he running on, but it can’t do so with a 
Declare; it's your responsibility to make sure that the function 
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you’re calling will be available. In this case, that means checking 
that the sysLem version is at least 8.5. But once you’ve done all 
tills, using the function you’ve declared is easy — just trail it like 
any ordinary REALbasic method. 

Let’s look at die Declare statements more closely. First, note 
that the declaration occurs within some other REALbasic method 
(subroutine or function). Just like a local variable, these 
declarations are local to where they’re declared; they will not be 
visible outside of this method. There Ls currently no way to make 
such a declaration global, though you could make a global 
wrapper function (as we’ve essentially done in this example). 

Tlie declaration always begins with die keyword "Declare” 
followed by either “Function” or “Sub”; REALbasic doesn’t actually 
care which you use, but by convention you use “Sub n when the C 
return type is void. Next Ls die name of the function, exactly as it 
appears in the external library, Tins is also die name used to 
invoke the function, unless you specify an "Alias” clause (which 
we ll cover a bit later). 

The next part of the declaration is the library name. This is the 
fragment name as it appears to the Code Fragment Manager, not the 
file name as it appears in the Finder; and unlike mast words in 
REALbasic, this name Ls case sensitive. Finding this name is not 
hard, but we’ll come back to it a bit later. 

Next come the function parameters, and finally the return type. 
This is where tilings get interesting. The documentation or header 
Files on which you’re basing your Declare probably specify the 
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parameter and return types with C syntax, rather than REALbasic. It 
may say something like "char * M or LL Str255” or something 
unpalatable. What to do? 

The Right Type for the Job 

Most of die work in creating a Declare statement is in finding 
die right conversions between the C types you see in the headers 
and documentation, and die REALbasic types that serve the same 
purpose. Fortunately you have tills article, which contains the very 
handy Table 1. Tills shows you some of the most common C types, 
and die corresponding REALbasic types you should use in a Declare 
statement. 


Table 1: C types and REALb asic 

EQUIVALENTS FOR DeOARE STATEMENTS 


C data type 

Declare ty pe 

Variable Type 

Boolean 

Boolean 

Boolean 

long 

Integer, OSType, Colorlnteger, String, Color 


int 

UInt32 

51nt32 

void* 

Ptr 

(etc.) 


OSType 

ResType 

DescType 

OSType (parameters only) 

String 

short 

unsigned short 
UIntl6 

Sint Id 

Short 

Integer 

float 

Single 

Single 

double 

Double 

Double 

Str255 

Str63 

Slr31 

unsigned char * 

PString 

String 

char * 

CString (parameters only) 

String 

WindowPtr 

WindowPtr 

Window 

WindowRef 

(parameters only) 


void* 

Ptr 

Memory BJot'k 

Ptr 



(or pointer to data structure) 



Fhe first column of this table is the data type the function is 
expecting, as you might .see it in the documentation or the C header 
file. The middle column shows the corresponding types you could 
use in the Declare statement. Finally, the last column shows the 
“natural” REALbasic types which most closely match die declared 
types; these are what you would pass (or get as a result) when 
calling die function. 
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REALbasie uses the type you specify in the Declare to figure out 
how much data to push onto the call stack when making the call; 
so the most important tiling is to get the size right, [f the function 
is expecting any 4-byte value, you can probably declare this as type 
Integer If you declare it as Short instead, REALbasie (when 
compiling for 68k processors) will push only two bytes, he function 
will try to grab four, and you'll almost certainly crash. 

Many of the type choices are very straightforward; if the 
function wants a float, declare it as a Single and pass it a number. If 
the function is expecting a Pascal string, declare it as type PString, 
and when you invoke the function, give it any ordinary string, 
REALbasie will automatically convert its internal string representation 
into a Str255 when calling the function (but note: if the function 
expects a shorter string than that, it s up to you to make sure your 
string isn’t too long before making the call). Or if the return type is 
a Pascal string, the returned value will lx* automatically converted 
into a normal REALbasie string. 

With other types, it's not so dear cut. Suppose the function 
expects a pointer. Should you declare tills as type Integer, or tyjx 
Ptr? The answer depends on the details. If it’s a function that 
allocates some data structure, returns you a pointer to it, and you 
simply pass it back to other functions without trying to peek at the 
data, then an Integer will do fine. REALbasie integers are four bytes, 
and a pointer is four bytes, so treating die pointer as if it were just 
a number will make life easiest for you. Most modem Apple 
toolbox calls, such as those in Carbon or QuickDraw 3D, are of tins 
sort, since the underlying dam structures are opaque. 

If, however, the function is expecting you to allocate storage 
for some data before calling die function, then a bit more work is 
required. In this case, declare the parameter as type Ptr. /Allocate 
the memory in the form of a REALbasie MemoryBlock, created 
with the NewMemoryBlock function (and be sure to make it the 
right size!). If the fund ion is expecting the data structure to be 
initialized with some values, you can use die MemoryBlock 
methods to stuff appropriate values into it. Then, pass this 
MemoryBlock to die function. From the function’s poinl of view, 
it just gets a pointer to some already-allocated memory. It may 
stuff values into this area, which you can later read by using [hose 
MemoryBlock methods again. 

Calling a Spade a Spade 

Your Declare statement must name the shared library which 
implements the function. In the case of a Windows DLL, you simply 
u.se the file name. In the Mac world, we don’t rely on file names, 
which are too frequently changed to be reliable. So you must u.se 
the fragment name as seen by die Code Fragment Manager (CFM). 
Most of the MacOS toolbox is in the fragment “InterfaceLib” (or 
“CarbonLib" for Carbon/OS X apps). But suppose you're calling 
some other library — for example, the “Quesa” high-level 3D 
graphics library. The CFM name of this library is “QuickDraw™ 3D” 
(because it’s a binary-compatible replacement for Apple’s 
QuickDraw 3D technology). If you don’t happen to have me 
around to tell you handy facts like this, how would you know? 

If you have ResEdit handy, it can give you the answer. Drop 
the library onto ResEdit and open the “drg n (code fragment) 
resource. This gives you a list of code fragments — usually there’s 


only one — and the name you’re looking for is labeled “Member 
Name". Copy that value, and paste it into your Declare statement 
as the library name. 

You can also use PEF Viewer, a free little utility from Apple. 
It also lists die code fragments iL finds, and even leLs you peek into 
the code, data, and loader information for each. (The last can be 
handy when Carbonizing — if the shared library you're using 
imports any symbols from anywhere other than CarbonLib, you 
probably can’t use h in a Carbon app.) The CFM name of the 
library is given right at the top, next to the disclosure triangle. 

If you don’t have either of these tools handy, you can use 
REALbasie itself. Just launch REALbasie, and drag the shared 
library file into the project window. It will appear there with its 
CFM name, rather than its file name. If you’re curious, what you 
have there is the alternative interface to importing functions from 
shared libraries — useful if you need a large number of functions 
from a single shared library, and you want them to lie global 
rather than local Since you’re using Declares rather than 
importing the library, you can just make note of the name, Lhen 
delete the library from your project. 

TBFiinpek to thjb Rescue 

Writing Declares lias always been a bit of an arcane art. Even 
armed with the knowledge in this article, you’ll find yourself 
wondering if it’s really worth the trouble w r hen you just need a quick 
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Mac toolbox call. Fortunately, there is a tool which can take much 
of the guess-work out of writing a toolbox-related Declare. 

TBFinder is an open-source REALbasic project coordinated by 
Fabian Lidman. First, you point it to your copy of Universal Headers 
— ie,, Apple’s toolbox interface files, which you can download 
from Apple s Development Kits web site. Then you can just find the 
toolbox call you need by searching or browsing, and it writes die 
Declare statement for you. There are some caveats, but in many 
cases it’s as simple as that. 

TBFindefs search window — what you see when you launch 
die utility — is shown in Figure 1. If you don’t know die name of 
the call you’re looking for, click "Browse” to get a nice hierarchical 
list of the functions defined in all the interface files, then just 
doubleclick the one you want. If you do know the name of the 
function you need, type it in the edit field; if you happen to know 
the header in which it’s declared, you can check the "Look first in:” 
checkbox and choose the appropriate header from die pop-up 
menu. Then click Search. 



Figure 1, WFinder search window , 

'Ihe result, assuming the function actually exists* is a window 
like that shown in Figure 2. 


S BSh owHi d e Contro IStri p 


B 


s ControIStrip h 


Pril The REALbasic declare statement goes: 

Dec I are Sub SBShowHideControlStrip Lib "interfaceLib" (ffhowli a- 
Boolean) lnllne68K("303CC1Gl AAF2") 


The original C declaration w-ss: 

extern void SSShowHideControfStrlp (Boolean shovlt) 

THREEVORD INLINE (0x303C, DxOI 01, Ox AAF2); 


I This call is net supported under Carbon. 




Figure 2. TBFinder result -window. 


the Copy command to move this text to the clipboard, or drag die 
little text-dipping icon directly into REALbasic, The other icons in 
die window are actually buttons that do things when you dick on 
them: the upper left icon by the header file name reveals that header 
file in the Finder; the text file icon by the original C declaration 
opens die header file (careful — Apple’s headers are set to open in 
Macintosh Programmers Workshop); and the glolie at upper right 
does a web search for die function name in Apple’s documentation. 

At the bottom of die window* you’ll notice a handy note telling 
you whether or not the function appears to be Carbon-compatible. 
If it is, you can use it in a Carlxin application by simply changing 
Lire library name to “CarbonLib”, In tile case of a classic application, 
TBFinder correctly identifies the library for you, using a big internal 
look-up table which I fervently hope was generated automatically 
by parsing the various system libraries. 

TBFinder also supports one other feature of die Declare that I 
not previously mentioned: the “InlinebBK” block. Many Mac 
toolbox calls on 68k machines are not shared library calls at all, but 
rather direct jumps to system traps. The C headers give die 
necessary machine language glue with the x WORD INLINE macros- 
TBFinder converts this to RB syntax, and even appends the extra 
glue needed in some cases by RB itself (Be sure to get the latest 
version of TBFinder; version 2,0, included on the REALbasic CD, 
does not do this correctly,) 

Finally, note that while TBFinder is invaluable, il isn’t infallible. 
In particular, it takes its best guess at the appropriate parameter 
conversions, but these often require human judgment (see Table 1 
again). Always double-check the parameter types TBFinder has 
chosen, and consider whether there are other choices that make 
more sense for you. 


Some Examples 

Now that we’ve covered all the basics, let's look at some real 
examples. We already saw one in Listing 1, used to toggle the 
“modified” flag on a window. Listing 1 shows another example, a 
call to the t<x>lbux routine ObscureCursor* which ttides the cursor 
tinlil the mouse is moved. As this routine lakes no parameters and 
returns no result, the declaration is very straightforward. 

listing 2: ObscureCursor 


OhscuftCursor 

Hide tlie cursor until the mooSe is moved (MaeOS only). 

Sub ObseureCursor() 

// Declare it with a "Sys" prefix to avoid a name dash 
#if TargetCarbon 

Declare Sub SysObscureCursor Lib “CarbonLib" Alias 
“QbscureCursor" {) 

Jelse 

Declare Sub SysObseureCursor Lib “InterfaceLib" Alias 
"ObEcureCursor ri () InIine6SK{‘‘ASSiTU 

ijlendif 

//(all it! 

SysOb sour eCur sor 
end Sob 


TBFinder’s search window — what you see when you launch 
the utility — is shown in Figure 2. The key bit is the second 
section* where the REALbasic syntax is shown. You can either use 


Note that in this example, Fve chosen to name the RFAIbasic 
subroutine exactly like the toolbox routine. That means that when 
I declare lire toolbox call within the subroutine, I’d have a name 
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clash unless 1 use the “Alias” option. “Alias" allows me to declare 
the system routine as SysObscureCursor, avoiding thus avoiding the 
dash, and allowing all other users of this subroutine to simply call 
“ObscureCursor 1 , 

Naturally, if you needed to use HideCursor/ShowCursor to hide 
the mouse even when it moves — say, because you're making a 
game and have a custom cursor or no need for a cursor at all — 
then the declarations would lx? very similar, But let's suppose you 
need to hide the cursor only within a rectangular region of the 
screen, perhaps because you're doing some animation there, or 
simply because you want to demonstrate a Declare involving a 
MemoryBiock. The toolbox call for this is ShieldCursor, TBFinder 
gives the declaration as; 

Declare Sub ShieldCursor Lib “InterfaceLib" (shiddRect as Rr, 
offsetPt as Point) Inline68KCA855”) 

Apple's documentation gives the first parameter as a Rea 
pointer, which TBFinder has rendered as type Ptr. From Table 1, 
you know that a MemoryBlock is needed for times like tills. We use 
the MemoryBiock to manually construct a Rea structure, recalling 
that a Rea is just a set of four short integers representing top. left, 
bottom, and right 

Dim m As MemoryBiock 

iri - NewMemoryElock(S) //8 hytes (four 2-hytie ifitt) 

m.Short( 0 ) = r.top 

m.Short(2) r.left 

in.Short(4) - r.top + r,height 

m.Short(6) * r.left + r,width 
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We can then pass this as the first parameter to ShieldCursor. 
What about the second parameter, "offsetPt"? Again referring to 
Apple's documentation, we find that this is the offset from the 
global coordinate system. In other words, it's the top-left corner 
of the window containing the rectangle to which we’re referring. 
TBFinder has left this declared as “Point", which is not a valid 
Declare parameter type. But since a Point is the same size as an 
Integer, we can fairly easily construct an integer that contains the 
information we need: 

Dim point As Integer 

H put pLv into tin: iiigh word, pLli into the low word: 

point = BitwiseAnd(self.top 1 65536, &HFFFFOGOO) 

point — BitviseOr [point., BitwiseArtd{self .left, &HOOOQFFFF)) 

Then, we simply change the Declare statement so that the 
second parameter is of type Integer, and were ready to go. The full 
listing for the ShieldCursor function is shown in listing 3- 

Listing 3: ShieldCursor 

ShieldCursor 

Hide Lilt cursor williin the given rectangle control. 

Sub ShieldCursor[r As RectControl) 

Declare Sub SysShieldCursor Lib "TnterfaceLib" Alias 
“ShieldCursor” (shieldRect as Ftr f offsetPt as Integer) 
Inline6BK.(“A855") 

Dim m As MemoryBiock 
Dim point As Integer 

// construct lire reel willlin which the cursor will he shielded 
m “ NewMemo r yE 1ock(8) // 8 bytes (four 24tylc mt$) 

m.Short(0) = r.top 
m,Short(2) - r.left 
m. Short (4) = r.top +■ r. height 
m .Short(6) = r.left + r.width 

// construct the point tUnt converts global to loal e<xfldlnflt« 
point « -self,top * 65536 self.left 

// pt.v in the high worclpt.h in the low wad 

// m;ikc die call 

SysShieldCursor m,point 
End Sub 

Let's end with a Windows declaration. I know, tills is a Mac 
programming magazine, hut sometimes you need it? deploy your 
app for dial Ollier Platform — and die ability Lo do so easily is one 
of REALbasic’s strengths. However, with the Declare statement, 
you're making a direct call to a toolbox or shared library routine; tills 
is rarely portable. So the first thing you'll need to do, is 
condiLionalize your code so shat Mac declares are included only in 
Mac builds, and Windows declares are included only in Windows 
builds. You can Lise either “#if TaigetMacOS” or “#if TaigetWin32” 
for this purpose. 

Next, you'll need information on the Windows API. Two good 
references are given at the end of this article. 

Finally, you'll need to construct the Declare statement by hand, 
TBFinder can't help you here; but with this article on your shelf, 
you're well-equipped for the task. So let s dive into an example. 

Windows applications can take command-line parameters, 
and these are often used to specify options or initial conditions 


26 


Declaring- External Functions in REALhasic 


MacTech • December 2001 















for the application. REALbasic can get these one at a time via the 
OpenDocument event, but in many cases it’d be preferable to get 
the whole command line, A search on the MSDN Online Library 
quickly leads to the GetCommandLine function, declared in the 
documentation as: 

LPTSTR GetCommandLine(VOID): 

This function takes no parameters, making our lives easy in 
that respect. And the return type, it turns out, is a C string of either 
ASCII or UniCode characters, 'this is an important point: many 
Windows functions come in both ASCII and UniCode versions, as 
signified under “Requirements” with a note such as “Unicode: 
Implemented as Unicode and ANSI versions on all platforms.” 
When you see this, it means that the function name given is not the 
real function name — you need to append "A” for die ASCII 
version, or U W' for the UniCode version. So the actual function 
name, for our purposes, is GetCommandLineA. 

Tiie return type in this case is an ordinary C siring. But, while 
REALbasic knows how to automatically convert its String type into a 
CString for use as a parameter, it can’t do die opposite conversion. 
So we need another approach. A C string is really just a pointer to 
some data, so we can declare the return type as “Plr”, and use a 
MemoryBtock to get at the data. The result is shown in Listing 4. 

listing 4 : GetCommandLine 

GetQMummUinc 

Get the ail! Win32 command line, including executable name and parameters. 

Function GetCommandLine() 

#If TargetWin32 
Dim m as MemoryBlock 

Declare Function GetCommandLineA Lib "KERNEL32.DLL” () as Ptr 
m - GetCoimnandlineA () 

Ret urn ra, cstring(O) // get die C siring to which m points 
#Else 

return "Command line available on Win32 only." 

#EndIf 
End Function 

There is one other trick that can sometimes make Windows 
declares easier. If you can Find a web site or other documentation 
with Declare statements for Visual Basic — such as the last reference 
given at the end of this article — then you can use those Declare 
statements in REALbasic almost verbatim. You'll just need to make 
a few changes: the "ByYah keyword can be omitted, and data types 
may have to l>e translated according to Table 1 (e g., use "Integer” 
where VB says long”). 


Conclusion 

REALbasic tries to abstract away the details of the underlying 
operating system, so you don’t have to worry about whether you’re 
running on classic MacOS, OS X, or some flavor of Windows. But 
sometimes you need more control. You may need to talk directly 
with the OS, or you may need access to some other shared library 
(such as OpenGL, for example). In those cases, die Declare 
statement is invaluable. 

The Declare statement allows you to do most of the same 
things you could do directly in G. There are some limitations; you 
can’t call a function that requires a callback, and you can t directly 


invoke a function pointer (eg., to call a macho entry point loaded 
via the CFBundie API). For those, you’il still need to write a plug¬ 
in. But for most other needs, you can Declare your external calls, 
providing a neater, more integrated solution. 

While Declare gives you nearly the power of C, it gives 
you nearly the complexity of C as well. Writing a Declare 
statement is error-prone, and if done incorrectly, can crash 
your program (and under Classic MacOS, the sy s tern as well). 
Deciphering the headers and documentation for the calls 
you're making requires some understanding of how things 
work in C or Pascal. But, with the tips gained here and a bit 
of study and experimentation, there will soon be little you 
can't do in REALbasic. 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 


Captured 


Using Sequence Grabber Components to 
Capture Video and Sound 

Introduction 

From its inception, QuickTime has included the ability to 
capLure video and sound data from devices attached to a 
Computer. Capturing video and sound together involves 
attaching a camera or other device that provides an audiovisual 
data stream to the computer, These devices include camcorders, 
laserdisc players, televisions, and videocassette recorders. We 
can capture sound alone using an internal or external 
microphone, or by attaching a CD player or other sound-only 
device to the computer. 

On the Macintosh models available in the early days of 
QuickTime, special add-on hardware (usually in the form of a 
NuBus or PCI card) was required to digitize an analog stream 
from an external device. Some models, beginning with the 
PowerMacintosh filOGAV, included built-in audiovisual hardware 
that allowed the user to connect external devices to RCA-type or 
S-video connectors. Nowadays all Macintosh computers (and 
many Windows computers) support FireWire connections, 
which allow a pure digital stream of audiovisual data to be sent 
to the computer from camcorders and other devices. 

At the lowest level, QuickTime interacts with video and 
sound hardware attached to a computer through software 
modules called video digitizer components (or just video 
digitizers) and sound input device driven, A video digitizer 
digitizes the video data stream, if necessary, and often provides 
additional services such as resizing the video, dipping exit 
portions of the video, and converting colors in the video. A 
sound input device driver manages communications between 
applications and the sound input hardware. 

Normally, however, we won t work with video digitizers or 
sound input device drivers directly. Instead, we ll work with a 
sequence grabber component, a part of QuickTime that provides 
a set of high-level APIs for capturing video and sound data. 


Since there is virtually always just one available sequence 
grabber component, we'll usually talk about the sequence 
grabber. The sequence grabber insulates us from having to know 
about any of the low-level details of video digitizers and sound 
input device drivers, and provides some additional sendees as 
well. We can use the sequence grabber to display video in a 
window, capture individual frames of video as pictures, and 
capture sequences of video frames as QuickTime movies. The 
sequence grabber can also capture sound data and synchronize 
the video and sound streams when displaying them in a window 
or capturing them to a movie file. 

In this article, we re going to see how to use the sequence 
grabber to capture video and sound data. Well develop an 
application, called QTCapture, which can capture video and 
sound from any available devices. The Test menu of QTCapture 
(on Windows, for a change) is shown in Figure 1. 


Test 

Video Settings... 

Ctrl+1 

Sound Settings,., 

Ctrl+2 

«/ Record Video 

Ctrl+3 

Record Sound 

Ctrl+4 

Split Track Files 

Ctrl+5 

Quarter Size 

Ctrl+6 

✓ Half Size 

Ctrl+7 

Full Size 

Ctrl+8 

Record 

Ctrl+R 


Figure 1: The Test menu of QTCapture 
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The first two menu items display dialog boxes that allow us to 
configure the video and sound capture settings. For instance, we 
c an set the video or sound source (the device from which we 
want to capture data) and the desired compression to be applied 
to the captured data. The third and fourth menu items allow us 
to .specify whether we want to capture video, sound, or both. 
Using the "Split Track Files” menu item, we can specify that the 
captured video and sound data be written to different files, (By 
default, the sequence grabber writes die video and sound data 
into the same output file.) The next block of menu items allows 
us to select the size of the monitor window t the window in 
which the incoming video stream is displayed. Figure 2 shows 
QTCapture's monitor window at its default size. 



We use the last menu item to begin recording data to a file; 
in QTCapture, the recording stops when the user clicks the 
mouse burton. 

Well begin by taking a look at the sequence grabber and 
where it fits into the QuickTime architecture. Then well see how 
to monitor the captured data, adjust the capture settings, and 
write the captured data into a file. 

Sequence Grabber Overview 

The sequence grabber is a pari of QuickTime that can be 
used to monitor video and sound sources, capture images 
and sequences of images, and synchronize captured sound 
and video. The sequence grabber provides two main services 
to applications: previewing and recording. To preview a data 
source is to display the captured data in a window on the 
screen (if it’s visual data) or to play back the captured data 
through the sound output hardware (if it's audio data). To 
record a data source is to write the captured data into one or 
more files on disk, 

Tn QuickTime version 2.5, the sequence grabber gained the 
ability to capture text data, using text digitizer components. A 
text digitizer component captures text data from external 
sources, such as the closcdca phoned data embedded in some 
television broadcasts. The process of capturing text is entirely 
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analogous to the process of capturing video or sound, and it 
would be easy to extend our sample application QTCapture to 
also capture text data and record it into a text track in a 
QuickTime movie. Because very few computers are equipped to 
capture text data, however, we won’t consider the sequence 
grabber's text capturing abilities further, 

A sequence grabber component does not communicate 
directly with either a video digitizer or a sound input device 
driver. Instead, it communicates with one or more sequence 
grabber channel components . The sequence grabber channel 
components, in turn, communicate with the video digitizer 
components and sound input device drivers. Channel 
components send control information to them and receive 
digitized data from them; the digitized data is then passed to 
other pans of QuickTime for previewing or recording. 

A sequence grabber component is also responsible for 
displaying any dialog boxes required to elicit capture settings 
from the user, such as the video settings dialog box shown in 
Figure 3- To do this, a sequence grabber component calls a 
sequence grabber panel component . A panel component then 
communicates with a channel component or the digitizer 
component to get and set the capture settings. 



Figure 3 The video settings dialog box 

Opening the Sequence Grabbing Components 

The QuickTime capture architecture may seem fairly 
complicated, but in practice our applications need to work 
directly with only three components: a sequence grabber 
component and two sequence grabber channel components. 
QTCapiure permits only one preview or record operation at 
a time, so it uses some global variables to keep track of these 
three components: 

SeqGrabComponent gSeqGrabber = MULL; 

SGChannel gVideoChannel = 0 ; 

SGChannel gSoundChannel - 0: 


We’U open an instance of a sequence grabber component 
by calling the OpenDefaultComponent function, like this: 

gSeqGrabber = 0 p e nD e f a ill t Comp onent (Se q Grab Comp onen t Ty pe, 0): 

We then need to initialize this component by calling the 
SGinitialize function: 

myErr = SGinitialize(gSeqGrabber): 

SGinitialize allocates any additional memory the sequence 
grabber may need and performs other necessary set-up for 
subsequent previewing and recording. 

Since we are going to be previewing video data, we need 
to tell the sequence grabber where to draw the previewed data. 
We do this by calling the SGSetGWorld function. With 
QTCapiure, our monitor window is simply a dialog box, which 
we open like this: 

gHonitor = GetMewMalogikMonitorDLOGID, Mini,. 

(WindovFtr) -H*) : 

If we successfully open this dialog box and initialize the 
sequence grabber, we can then set the sequence grabber’s 
graphics world by calling SGSetGWorld: 

myErr = SGSetGWorld(gSeqGrabber, GetDialogPorttgMonitor) ( 

MULL); 

It’s even easier to open the two sequence grabber channel 
components we need; we just call SGNewChannef passing in the 
media type of the data to be captured: 

SGNevChannel(gSeqGrabber, VideoMediaType T &gVideoCfaannel); 
SGNewChanne1(gSeqGrabber, SoundMediaTypc♦ &gSoundChanne1); 

Our actual code, of course, checks the result codes returned by 
SGNewChanneL 

Configuring Video Channels 

Before we can begin previewing or recording from these 
channels, we need to do some preliminary configuration of the 
channels and of our application. The first thing we want to do 
is set the channel usage flags of the video channel. These flags 
tell the channel component what operations w r e T re going to want 
it to perform. Currently, these channel usage flags are defined 
(in the file QuickTimeComponents.h): 

enum l 

seqCrabRecord “ 1. 

seqGrabPreview = 2. 

seqGrabPlaySurlngRecord “ k 

\i 

These flags arc fairly self-explanatory. The seq Grab Record and 
seqGrab Preview flags tell a sequence grabber channel 
component that its channel will be used for recording and 
previewing, respectively. The seqGrabPlay During Record Hag 
indicates that we are going to want to preview the captured data 
while we are recording it. The previewed video will get 
choppier if we enable this flag (since we're devoting some 
processor time to recording), but at least it will continue playing. 
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In QTCapture, we want to enable all of these flags for the 
video channel. So we ll call SGSetChannelUsage like this: 

myErr = SGSetChannelUsage(gVideoChannel, 

seqGrabFreview | seqGrabRecard | seqGrabFlayDuringRecord); 


We also want to set the initial size of our monitor window 
to its default size, which is half the size of the video digitizer's 
active source rectangle (that is T the portion of the digitizer's 
source rectangle that actually contains video data). We call the 
SGGetSrcVideoBounds function to get the size of the active 
source rectangle and then we resize our monitor window to half 
that size, using the code in Listing 1. (Well see the complete 
definition of GTCapJnit later, in Listing 3.) 


Listing 1: Setting the initial size of the monitor window 

QTCapjnit 


short ntyWidth; 

Ehort njyHeight: 

myErr = SGGetSrcVideoBounds(gVIdeoChannel, 

&gAetiveVideoRect); 
if (myErr = noErr) l 

myWidth = (gActiveVideoRect,right - gActiveVideoRect.left) 

/ 2 ; 

myHeight “ (gActiveVideoRect.bottom gActiveVideoRect,top) 

t 2 : 

SizeWindow(GetDialogWlndow(gMonitor) T myWidth. tnvHeight. 


The last tiling we need to do is tell the channel component 
the size of the display boundary rectangle, which is the 
rectangle in which the previewed video data is to be displayed. 
We can do this by retrieving the current size of the monitor 
window's content region and then passing that size to the 
sequence grabber channel component by calling 
SGSetChannelBounds, like so; 

GetPortBounds [GetDialogPort (gMonitor), ktnyRect) ; 
myErr = SGSetCbanTielBoundstgVideoGbarmel h &myRect); 


If any of this configuring should fail, then we won't be able 
to capture or preview data from the video source. In that case, 
we want to close down the video channel and set the global 
variable gVideoChannel to NULL, indicating that we don't have an 
open video channel: 

if (myErr != noErr) \ 

SGDi sposeChannel(gSeqGrabber, gVid eoCharme1}: 
gVideoChannel = NULL; 

I 


Configuring Audio Channels 

Our audio channel is somewhat easier to configure. First, 
we want to set the channel usage, like this: 

myErr = SGSetChannelUsage(gSoundChannel, 
seqGrabPreview | seqGrabRecord); 


hand, we do want the sound to be played while it’s being 
previewed. Even in that case, however, w r e want to make sure 
that the volume of the sound played back is low enough to 
avoid any feedback that might arise if the sound input hardware 
(usually, the microphone) happens to he too near the speakers. 
So well call SGSetChann el Volume to set the sound channel 
volume to a fairly low setting; 

myErr = SGSetChannelVolumeEgSoundChanoel, 0x0010); 

One other thing we want to do is add some sample rates to 
the Rate pop-up menu in the sound settings dialog box. By 
default, the only rates that appear in that menu are those that the 
underlying sound hardware indicates it can handle natively. On 
most modem Macintosh computers, for instance, only the 44.1 
kHz rate appears (as seen in Figure 4), and on slightly older 
models only the 44.1 and 22,050 kHz rates appear. 


Sound 


Rate 44.100 kHz 


Size: Q S btts @ 16 biti 
Use 0 Mono ® Stereo 



Figure 4: 7he default Rate pop-up menu 


The sequence grabber provides the SGSetAddftionalSoundRates 
function, which we can use to add some more rates to that menu. 
Listing 2 shows the code we use to add another 5 common sound 
sample rates to the Rate jxjp-up menu. Ihe expanded menu is 
shown in Figure 5, 


Listing 2; Adding sample rates to the sound settings 

dialog box _ 

QTCapjnit 


Handle myRates = NULL: 

myRates = NewEandleClear{5 * * sizeof(Fixed)); 

If (ntyRates NULL) ( 

•({long *) pmyRates) + 0) = Long2Fix(8O0O); //8kHz 

* Liang * j i *ntyRates) + i: - Long2Fix( 11025): // 11kHz 

•((long *](*myRates) + 2) - Lemg2Fix(I600G); //16kHz 

* ((long •) (*ntyRfltes) + 3) = Loug2Fix{22050); //22kHz 

‘((long *){ *myRatesj +4) - Long2Fi.x(32Q0Q): //32JtHz 

SGSetAdditianalSoundRatesEgSoundChaimel. myRates); 

DisposeHandlefayRates); 


You’ll notice that we did not set the seqGrabPlayDuring Record 
Hag. This makes good sense, since we don't want the charmers 
sound data to be played while it's being recorded. On the other 
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Once again, if any of this configuring should fail, we want 
to close down the sound channel and set the global variable 
gSoundChannet to NULL: 

if (myErr !“ noErr) ] 

SGDisposeChanneI(gSeqGrabber. gSoundChannel); 
gS a urtd Channel - MULL; 

I 


Previewing 

Let’s reflect cm what we've accomplished so far. We’ve 
opened an instance of the sequence grabber component. We’ve 
also opened two sequence grabber channels — one for video 
and one for sound — and we’ve configured both of those 
channels, We’ve also opened our monitor window and resized it 
to its default si/e. We haven’t yet displayed the monitor window, 
however, so let’s do that now: 

HaeShowWindow(GetDialogWindaw(gMonitor)): 

All that remains, then, is to start the preview ing. We can do that 
with a single call: 

tnyErr = SGStartPreview(gSeqGrabber): 

W r e also need to make sure that the sequence grabber gets 
some processor time periodically. We do that by calling SGIdle 
fairly often, In QTCapture, we’il insert these lines of code into 
the application function QTAppJdle: 

if (gSeqGrabber 3= NULL) 

SGIdle(gSeqGrabber); 


And we’re done! The application will display the captured 
video in the monitor window and play the captured sound 
through the computer’s speakers. Listing 3 shows the complete 
definition of the QTCapJnit function, which performs all the 
necessary seLup and then starts the preview rolling. 

Listing 3= Initializing and the sequence grabber 

QTCapJnit 

ComponentResult QTCap_Inlt {void) 

{ 

ComponentResult myErr = noErr: 
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// open the sequence grabber component 

gSeqGrabber = OpenBefaultCGmponenttSeqGrabCompQnentType. 

Ok 

if (gSeqGrabber = NULL] ( 
myErr - cantQpenHandler; 
goto bail; 


// open the monitor window 

gMonitor = GetNewDialog (kMoriitorDLGGID, NULL, 
(WindowPtr)-1L): 
if (gMonitor = NULL) { 
myErr ~ memFullErr; 
goto bail; 


‘((long *)(’myRates) + 2) — Long2Fix( 16000); //16kHz 

* ((long *) ('‘myRates) +3) = Long2Fix( 22050) ; // 22kHz 

'((long *)(’myRates) + 4) = Long2Fix(320G0); //32kHz 

SGSetAdriitionalSoundRatesCgSoundChannel* myRates); 

DispaseHandle(myRates) ; 

] 

II if an error occurred while configuring sound channel, dispose of it 

if (myErr != noErr) f 

SGOisposeChannel(gSeqGrabber. gSoundChannel): 
gSoundChannel = NULL; 

1 

I 

J 


SetPortDialogPort(gMonitorj ; 

KacHoveWindDw(CetDiaiogWindow{gNonitor), 10. 

30 + GetMBarHeight()* 0); 

II initialize the sequence grabber 

myErr = SGlnitialize(gSeqGrabber) ; 

if (myErr = noErr) 1 

II configure the sequence grabber component 

myErr “ SGSetGWorld(gSeqGrabber, GetDialogFort(gMonitor). 
NULL); 

if (myErr 1- noErr] 
goto bail; 


II create a video channel 

myErr " SGNewCharmel(gSeqGrabber, VideoMediaType, 
^gVideoChannel); 

if {(gVideoChannel 1= NULL) && (myErr — noErr)) ( 
short myWidth: 

short myHeight; 

Rect myRect; 


myErr = SGGetSrcVideoBounds(gVideoChannel, 
kgActiyeVldeoRect) ; 
if (myErr — noErr) { 

myWidth “ (gActiveVideoRect.right 

gActiveVideoRect Cleft) / 2; 
myHeight - [gActiveVideoRect.bottom - 

gActiveVideoRect,top) I 2; 
SizeWindowfOetDialogWindow(gMonitor) . myWidth, 
myHeight. false); 


J 


myErr = SGSetChanneiUsage(gVideoChannel, 

seqGrabPreview | seqGrabRecord | 
seqGrabFlayDuringRecord): 
if (myErr = noErr) f 

GetPortBounds(GetDialogPort(gMonitor). kmyRect); 
myErr 3 SGBetChannelEaunds(gVideoChannel, &myRectk 


] 


II display the monitor w indow 

MacShav?Window(GetDialogWindGw (gMonitor)) ; 

II start previewing 

if (myErr = noErr) 

myErr = $GStartFreview( gSeqGrabber}; 


bail: 

II if an error occurred, clean up 

if (myErr 1= noErr) 
QTCap_Stop(); 

return(myErr) ; 


We call GTCapJnit when QTCapture starts up, so that the 
monitor window appears immediately at application start-up 
time. Our menu-adjusting function GTApp_AdjustMenus contains 
these lines, which disable the "Close 11 menu item in the File 
menu if the monitor window is the Irontinost window: 

if (QTFrame^GetFrontAppWlndowO — 

QTF ram e_Get WindowRef er en c eF romWind ow 

(GetDialogUindow(gMonitor))) 
QTFrarae^SetMenuItemState(myMenu* TDM FILECLQ&E. 
kDisableMenuItem); 

So the monitor window will remain open for as long as 
QTCapture is running. When QTCapture quits, we close the 
monitor window and shut down our sequence grabber 
components by calling the QTCap_Stop function (defined in 
Listing 4X 


II if an error occurred while configuring video channel, dispose of it 

if (myErr 1* noErr) I 

SGDisposeChannei(gSeqGrabber. gVideoChannel)J 
gVideoChannel ■ NULL; 

J 

] 

II create a sound channel 

myErr = SGNewCharmel(gSeqGrabber, SoundMediaType. 

&gSoundChannel); 

if ((gSoundChannel 3= NULL) && (myErr = noErr)) ( 
Handle myRates = NULL; 

myErr = SGSetChanneiUsage(gSoundChannel, 
seqGrabPreview I seqGrabRecord); 
if (myErr = noErr) [ 

II set the volume low to prevent feedback when we start the preview 

II (in case the mic is anywhere near i he speaker) 

myErr = SGSetChannelVolume(gSoundCbannel, 0x0010); 


II add some sample rates to the Sound settings dialog box Rate pO|>up menu 
myRates = NewHandleClear (5 * sizeof'(Fixed)} : 
if (myRates !- NULL) [ 

‘{(long *)(’myRates) + 0) = Long2Fix(8000); //8kHz 
* ((long. Rates) + 1) - Long2Fix(11023) ; //UkHz 


Listing 4: Shutting down the sequence grabber 

QTCap Stop 

void QTCap Stop (void) 

t 

if (gSeqGrabber 1= NULL) I 
SGStopfgSeqGrabber]; 

CloseComponenr(gSeqGrabber); 
gSeqGrabber - NULL; 


if (gMonitor I 13 NULL) ■[ 
DiaposeDialog(gMonitor): 
gMonitor - NULL; 

] 

1 


You’ll notice dial we didn't explicitly close the sequence grabber 
channel component instances gVideoChannel or gSoundChannef 
The sequence grabber does that automatically for us when we 
call CloseComponent on the sequence grabber component 
instance we opened. 
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Channel Settings 

QTCapmre includes menu items that display dialog 
boxes in which the user can configure the settings of the 
video and sound channels. We've already seen the sound 
settings dialog box (in Figures 4 and 5) and the video 
settings dialog box (in Figure 3); Figure 6 shows another 
pane of the video settings dialog box. 



Figure 6: 1he video settings dialog box 

In both cases, we display the settings dialog box by calling the 
SGSettingsDiatog function, passing in our instances of the 
sequence grabber component and the appropriate channel 
component. There are, however, a few extra details that we 
need to consider when we call SGSettingsDialog. 

Handling Update Events 

As you can see, the settings dialog boxes are movable 
modal dialog boxes, This means that, on Macintosh computers, 
we ll also need to specify a modal dialog filter function to handle 
idle events and to pass update events to windows located 
behind the settings dialog box. If we didn't do this, and if the 
user were to move the settings dialog box on top of another 
QTCapture window and then move il away, that window would 
nol get redrawn. (On Windows computers, as we’ve seen in 
earlier articles, paint messages are sent directly to the affected 
window, so we don't need a modal dialog filter function.) 

We’ve already developed a basic modal dialog filter 
function that is able to redraw any movie or image windows 
that our application has open, (See, for instance, “Honey, 1 
Shrunk the Kids" in Mac Tech, February 2001J In the present 
case, we also want to redraw the monitor window itself, in 
case it gets covered up and then uncovered by a settings 
dialog box. The sequence grabber provides the SGUpdate 
function, which instructs the sequence grabber to refresh its 
display. In theory, we could use SG Update here, except for 
one small problem: QuickTime steals our sequence grabber 
component instance while the video settings dialog is 
displayed. Look again at Figure 6 and notice that the right- 


hand side of the dialog contains a pane in which the 
previewed video data is displayed. The input for that pane is 
provided by our very own sequence grabber component, 
gSeqGrabber. So we can call SG Update until the cows come 
home and our monitor window will never get refreshed. 

There is a simple workaround to this theft. We can take a 
snapshot of the monitor window just before we call 
SGSettingsDiatog to display a settings dialog box, and then 
redraw the monitor window using that snapshot whenever 
necessary. Listing 5 shows our function 
QTCap_GetChannelSettings. which well call to display a video or 
sound settings dialog box. As you can see, we call SGGrabPict 
Lo get a picture that contains the current image in the monitor 
window. Then we call SG Settings Dialog and later clean up by 
disposing of die grabbed picture. 

Listing^: Displaying a settings dialog box 

QTCapjGetChinDdSetangs 

static Component Result QTCap_GetChanne'l Settings 
(SGChannel theChannel) 
f 

SGModalFiiterUFP myFilterlIPP - NULL; 

ComponentResuI 1 nyErr " noErr: 

// get rid of any existing monitor picture 
if (giionitor PICT != NULL) ! 

KlllPieture(gMonitorPICT); 
gMonitorPICT = NULL: 
f 

// get the picture currently in the monitor window 
SGGrabPict(gSeqGrabber. ^MonitorPICT, NULL. 0* 
grabPlctOffScreen); 

// display the settings dialog box 

ikf TASGETJJSJ4AC 

myFilterUFF = NewSGModalFilterliFP(QTCap_SDModaiFilterProc); 
fendif 

nvyErr - SGSettIngsDiaiogtgSeqGrabber. theChannel, 0. NULL, 

OL, myFilterUPP, (long)gttonitor); 

#if TARGET_QS_MAC 

DisposeSGModalFilterUFP(myFilterUPP}; 
fendif 

H get rid of the monitor picture 

If (gMordtorPTCT != NULL) I 
KillPicture(gMonitorPlCT) : 
gMonitorPICT - NULL: 

J 

return(myErr)t 

1 

Strictly speaking, we need lo call SGGrabPict only when 
we’re about to display the video settings dialog box, But the 
code for redrawing die uncovered monitor window is in fact 
much simpler if we grab the picture in die monitor window 
in both cases (that is, for both the video and sound settings 
dialog boxes). 

Listing 6 shows our complete sequence grabber modal 
dialog Filter function. It's pretty much identical to the modal 
dialog filter functions we've encountered hitherto, except that h 
contains code to determine whether the window to be updated 
is the monitor window gMonitor, If it is, we gel the size of the 
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monitor window and draw the saved snapshot into that window 
by calling DrawPicture. As you can see, QTGap_SGModa[RlterProc 
assumes that the theRefCon parameter is a pointer to die monitor 
dialog box. If you look back at Listing 5, you 1 !! see that indeed 
we pass gMonitor as the last parameter to SGSettingsDialog. 


QTFr ame_Han d 1 ©Event ((Eve ntR.ecord * ) th eE v e nt) : 
myEventHandled - false: 

) 

break? 

case nullEvent: 

// do kUe time processing for ail open windows in our window list 
if (gAppInForeground) 

QTFrame_IdleMovieWindDws(J: 


Listing 6: Handling events 


QTCap_SGMo(MFilterProc 


myEventHandled = false; 
break: 


#if T ARGET_0S _M AC 

static PASCAL_RTN Boolean QTCap_SGModalFliterProc 
(DialogFtr theDialog, const EventRecord 
short 'thelteraHit, long theRefCon) 

( 


Boolean 

WindowPtr 

RgnHandle 

GrafPtr 

Rect 

DialogPtr 


myEventHandled & false: 
myWindow - NULL; 
myWindowRgn = HULL: 
mySavedFort: 
myRect; 

myMonitor = (DialogFtr)theRefCon: 


*th©Event* 


switch (theEvent->what) I 
case updateEvt: 

// find out which window need* to hr updated 
myWindow = (WindowPtr)theEvent-^message: 
if (myWindow = GetDialogWindow(myMonitor)) ( 

// update the monitor window, using the stored picture 

GetPort (SimySavedPort); 

MacSetPort(GetWindowFort(myWindow)): 

#if TARGET_API_MAC_CARSON 

GetPortBoundsCGetDialogPort(myMonitor)> &myRect); 

tfelse 

myRect = myWindow->portRect; 

tfendif 


default: 

myEventHandled - false: 
break: 

] 

// let the OS's standard filter proc handle the event, if it hasn’t already been 
handled 

if (gHasNewDialogCalls && (myEventHandled = false)] 
myEventHandled “ StdFilterProc(theDialog, 

(EveiitRecord *)theEvent* theltemHit) ; 

return(myEventHandled); 

) 

(fend if 


Displaying the Settings Dialog Boxes 

Now we've got the necessary tools we need to display the 
sound and video settings dialog boxes. Listing 7 shows die 
definition of the GTCap _GetSoundSettings function. Pretty 
simple, eh? 


// draw the saved monitor picture into the monitor window 
if (gMonltorPICT 1- NULL) 

DrawPicture(gNonitorPICT, kmyRect); 

// dear the update region 
EeglnUpdato(myWindow); 

EndUpdate(myWindow); 

MaeSetPort(mySavedPort); 
myEventHandled - true; 

[ alee if {(myWindow 1= NULL) && 

(myWindow E= GetDialogWindowftheDialog))) 1 
// update Ulc specified window. If il s behind the modal dialog box 


Listing 7: Displaying the sound settings dialog box 

QT( hp_GetSoimdSetti ngs 

void ^TGapJGetSoundSettings (void) 

t 

QTCap_GetChannelSettings(gSoundChannel); 

I 

\ 

For [lie video settings dialog box, however, we need to 
do a little more work. The principal complication is thai 
some of (he user s selections may cause the video digitizer’s 
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active source rectangle to change. Indeed, the user can even 
change the video digitizer itself, by selecting a new video 
input source. So we need to pay attention to any size 
changes that may occur and then recalculate and reset the 
size of the monitor window accordingly. 

Before we call QTCa p_GetCh an ne [Settings on the video 
channel, we want to pause the preview operation. We can do 
that by calling SGPause: 

SGFause(gSeqGrabher. true); 

At this point, we can go ahead and call 
QTCap_GetChannelSettings > passing in the video channel 
component instance: 

myErr = QTCap_GetChannelSettings{gVideoCbannel); 
if (myErr I* noEtr) 
goto bail: 

[f QTCap_GelChannelSetiings returns successfully, well retrieve 
the new video boundary rectangle: 

SGGetSrcVideoBounds(gVideoChannsl, kmyNewActIveVideoRect): 

The video source boundary rectangle defines the size of the 
source video image being captured by the video channel. The 
active source rectangle is usually a part of the video source 
boundary rectangle. 

Now we need to adjust the size of the monitor window if 
the active source rectangle has changed size (that is, if 
myNGwActiveVideoRect differs from gActEveVideoRect). Listing 8 
shows the code we execute in that case, 

Listing 8: Adjusting the size of the monitor window 

QT( lap GliVkIl* jSct 

if (!MacEqualKect{4gAcLiveVidfeoRect, &mvNewActiveVideoRect)) 

[ 

short myDivisor = 1; // assume gPulISlze 

if (gQuarterSize) 
myDivisor = 4: 
else if (gHalfSize) 
myDivisor - 2: 

myWidth = (myNewActiveVideoRect.,right - 

myNewActiveVideoRfisct,left) / myDivisor: 
mylieight “ {myNewActiveVideoReet,bottom 

ujyNewActiveVideoRect.top) / myDivisor: 

gActivoVirieoReet = myNewAcTiveVideoRect; 
SizeWindow(GetDialog.Window(^Monitor) t myWidth, myHeight, 
false): 

GetFortBounds(GetDialogFort(gfionitor) , kmyRect) ; 
SGSetChannelBounds[gVideoChannel, SmyRect); 

1 

Note that wc resize the monitor window and then reset the 
display boundary rectangle. Listing 9 shows our complete 
definition of QTCap_GetVideoSettings. 

Listing 9: Displaying the video settings dialog box 

QTCap_Ge[VideoSettmgs 


Rect my tie w Ac tiveVideoRect; 

short myWidth, myHeight; 

GrafPtr mySavedPart: 

SGModalPiIterDPP myFilterUPF = MULL: 

Rect myRect; 

ComponentResult myErr = aoErr; 

if gel our current state 

GetFort (SimySavedPort): 

// pause previewing 

SGPause(gSeqGrabber, true): 

// display the video sei tings dialog box 

myErr = QTCap_GetChaunelSettings(gVideoChannel): 
if (myErr 1“ noErr) 
goto hail: 

// retrieve the user s choices 

SGGetSrcVideoBounds(gVideoChannel, kmyHewActiveVideoRect): 

// set up our port 

SetPortDiaiogPort(gMonitor); 

// has our active rectangle changed> 

// if so, it's because our video standard changed (e.g., NTSC to PAL) 

// and we need lo adjust our monitor window 

if [IMacEqualftect(&gActiveVideoRect. 
fonyNewActiveVideoRect)) \ 
short myDivisor = 1; // assume gPullSizc 

if {gQuarterSize) 
myDivisor = 4; 
else if (gHalfSize) 
myDivisor = 2: 

myWidth = (myNewActiveVideoRect,right - 

mylto ActiveVideoRect,left) / myDivisor: 
myHeight = (ngrHewActiveVideoReet.bottom 

myNewActiveVideoRect.top) / myDivisor: 

gActiveVideoRect = myHetfActiveVideoRect: 

SizeWlndow(GetDiaiogWindow(gMonitor). myWidth, myHeight, 
false): 

GetPortEounds(GetDialogFort.(gMonitor). kmyRect ); 
SGSetGhannelBounds(gVideoChannel„ ^myRect): 

1 

bail; 

MacSetPart(mySavedPort): 

#if JTARGET_OS_MAC 

// this is necessary, lor now, to gel the grab to siari again after The dialog goes away; 
ff for some reason ihc video dcstRect never gets reset to point back u> die monitor 
// window 

SGSetChannelsounds(gVideoChannel. &f^Monitor-ZportRnct)): 
jfsndif 

// restart previewing 

SGPause(gSeqGrabber, false!: 


As you can see, on Windows we call SGSetChannelBounds 
to reset the channel bounds rectangle to the size of the monitor 
window. 


Monitor Window Size 

While we're on the subject of resizing the monitor window 
to fit the active source rectangle, let s see how QTCapture 
handles the three menu items that adjust the size of the monitor 
window. The application function GTApp Han die Menu contains 
the lines of code shown in Listing 10, 


void QTCap_GetVideoSettings (void} 

I 
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listing 10: Handling the size-related menu It ems 

QTGip_GetVideo Settings 

case H3H_Q1IARTER_SIZE; 

QT€ap_ResizeMonitorWiridow(4} : 

mylsEandled = true: 

break; 

case IDiLHALEJ&IZE: 

QTCap_ResiseMo nit o r Wind ow(Z); 

mylsHandled = true: 

break; 

case IDM_FULL_SIZE: 

QTCap_ResiseMonitorWindow(1}: 

mylsHandled = true: 

break; 


In all three cases, we call the function QTCap_Resize Mon do rWi ndow, 
passing in the appropriate divisor. OTCap_Res ize Mo n tto rWi ndow is 
defined in Listing 11; it should be fairly clear, given the similar code 
we just encountered in Listing 9 

Listing 11: Resizing the monitor window 

QTCap_Resize Monitor Window 

void [iTCap_ResizeMonitorWtndow (short theDivisorI 

i 

Rect myRect; 

short my Width, myHeight; 

GrafPtr mySavedFort; 

ComponentResult myErr = noErr: 

// calculate the new width ami height 

m.y Width = (gActiveVideoRect, right gActiveVideoRect. left) 

/ theDivisor; 

myHeight 3 (gActiveVideoRect.bottom gActiveVideoRect,top) 

/ theDivisor; 

gQUarterSize = (theDivisor — 4) ; 
gHalfSize = (theDivisor ” 2); 
gFullSiEie = (theDivisor = 1) r 

// resize the monitor window 

GetFortf&mySavedFort); 

SetPortDialogPort(gMonitor) ; 

SGFause(gSeqGrabber t true): 

SizeWindow(GetDiaiogWindow(gMfvn1toeJ , myWldth, myHeight H 
false) ; 

CetPortEounds(GetDialogPott(gMonitor). ^myRect); 
SGSetCbannelBounds(gVideoGhanoel P &myRect); 

MacSetPort(mySavedPort): 

SGPause(gSeqGrabber. false): 


We resize the monitor window Lo its new height and width 
by calling SrzeWindow. We also reset the video channel's display 
boundary rectangle (the rectangle in which the previewed data is 
displayed) by calling SGSetChannelBounds. Because the display 
boundary rectangle completely fills the content area of tire 
monitor window, we are able to keep the geometry calculations 
fairly simple. In a more typical case, where the preview occupies 
only part of a window, we'd need to do some more complicated 
calculations. If you are interested, rake a look at the HackTV 
sample code package cited at the end of this article. 


Recording 

Finally it’s time to see how to use the sequence grabber to 
record captured video and sound data into a movie file. This is 
actually a fairly simple task, as the sequence grabber provides 
the SGStartRecord and SGStop functions that we can use to start 
and stop recording. First, however, we need to tell the sequence 
grabber where to put the captured data. 

Setting the Output File 

The first thing we want to do is have the user select a file 
to hold the captured data. Well use our framework function 
QTFrame_PutFile and then call DeleteMovieFile if the selected file 
already exists and the user tells us to overwrite that existing file, 
as shown in Listing 12. 

Listing 12: Eliciting an output file from the user 

QTCap_ Record 

QTFraute_FutFile (tnyPrompt, inyFileName, SmyFile, 

&tnyIsSeleeted. SraylaReplacing) : 
myErr = mylsSelected ? noErr : userCanceledErr: 
if [myErr 1= noErr) 
goto bail; 

// delete any existing the movie file, If the user ,so instructs 
if (mylfiReplacing) 

DeleteMovieFile (&myFile); 

Next well call the SGSetDataOutput function to set the 
selected file as the output file for the recorded data. The 
sequence grabber stores the data in the file as a Quicklime 
movie, complete with the requisite movie metadata (that is, the 

movie atom) and the appropriate sound and video tracks. 
myErr - SGSetDataOutput(gSeqGrabber, frnyFile, seqGrabToDisk); 

The third parameter to SGSetDataOutput is a set of Hags that 
control various aspects of the recording operation. Currently 
these flags are available: 


emun 1 

seqGrabToDisk ” 1 ( 

BeqGrabToMemory •= 2. 

seqGrabDontUseTempMemory = 4. 

SeqGrabAppendToFile “ 8 f 

aeqGrabDontAddMovieResource = 16, 

seqGrabDontMflkeMovle ** 32, 

seqGrabPreExtendFile = 64. 

seqGrabDataProcIslnterruptSafe = 128, 

seqGrabDataProcDoesGverlappirigReads - 256 


The first two flags, seqGrabloDisk and seqGrabToMemory, are 
mutually exclusive. The seqGrabToDisk flag tells the sequence 
grabber to write the captured data to the output file as the data is 
captured; the seqGrabToMemory flag tells the sequence grabber first 
to record the data into memory and then to write it into the output 
file only when the recording operation is complete. Using the 
seqGrabToMemory flag can result in better performance (that is, 
fewer dropped frames) but it limits the amount of recorded data to 
the memory available to our application, (It s worth noting that this 
technique for avoiding dropped frames is far less necessary these 
days, as hard disks are significantly faster than in the early days of 
QuickTime.) As you can see above, QTCapture specifies the 
seqGrabToDisk flag. The remaining flags are lor more specialized 
capture operations and we won t consider them further. 
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Setting Channel Output Files 

By default, each open channel writes its data into the file 
specified by the SGSetDataOutput function. It's possible, 
however, to configure the sequence grabber to record different 
channels into different files. To do this, we need to create a new 
sequence grabber output and attach that output to a particular 
channel We create a new channel output by calling the 
SGNewOutput function, and we attach that output to a channel 
b\ calling the SGSetChannelOutput function. 

When we call SGNewOutput, we need to specify the output 
file by passing in a data reference to the destination file; this is 
unlike SGSetDataOutput, where we passed a pointer to a file 
specification record. (See “Somewhere I’Ll Find You" in MacTech, 
October 2000 for a discussion of working with data references,) 
In QTCapture, we prompt the user for a channel output file by 
calling QTFrame_PufFile, so we need to create an alias data 
reference for that file: 

myErr - QTNevAlias(&myFile, ^myAliasHandle, true): 

And then we can call SGNewOutput and SGSetChannelOutput. 
like this: 

SGNewOutput(gSeqGrabbee» (Handle)ntyAliasHandle„ rAliasType, 
seqGrabToDisk, fonyOutput); 

SGSetChannelOutput(gSeqGrabber, theChannel, myUutput): 

Notice that SGNewOutput also takes a parameter that specifies 
the desired recording options; in tills case, we'll pass the same 
flag, seqGrabToDisk. that we earlier passed to SGSetDataOutput. 

QTCapture maintains a global variable, gSplitTracks, that 
indicates whether the user wants to capture video and sound 
data into different files. Before we begin recording, we inspect 
that variable and, if necessary, prompt the user to select the 
channel output files. Listing 13 shows the code that does this. 

Listing 13= Eliciting channel output files from the user 

QTCap^Rrcord 

if ((groundChannel != NULL) && gHecordSound fcfc 

(g Video Channel != NULL) && gRecord Video M gSplitTracks) •! 
my Err ■ QTCap„SetTrackFileCgVide-oChanne] , kVideoSaveProrap’E * 
kVideoSaveMovieFileNaine); 
if (myErr t- noErr) 
goto bail: 

myErr = QTCap_SetTrackFile(gSaundChannel„ kSaimdSaveProrapt. 

kSoundSaveMovieFileName); 
if £myErr I" naErt) 
goto bail: 

I 

As you can see, we call the function QTCap_SetTrackFie, 
defined in Listing 14, to do most of the work. 
QTCap_SetTrackFile just assembles the pieces weVe encountered 
so far in this section. 

Listing 14: Setting a channel output file 

QTCap_SetTrackFik 

static ComponentResult GTCap_SetTrarkFile 

(SGChannel theCharmel, char *thePrompt, 
char * theDefaul tName) 

t 


FSSpee myFils: 

Boolean JnylsSelected = false; 

Boolean mylsReplacing = false: 

StringPtr my Prompt “ 

QTUtils_CotEVertCToPascalStting [thePrompt): 
StringPtr nryFileName = 

QTUt i 1 s_Conve rtCToPa s c a 1 St r i n g {th eDe fml tName}: 

S GOui put myOutput; 

AliasHandle myAliasHandle = NULL: 

OSlrr myErr * noErr; 

// prompt the user for new fite name 
QTFrame„FutFile(myPrompt* myFileName, StmyFile, 

&myIsSetacted, &myIsReplacing); 
myErr - mylsSelected ? noErr : userCanceledErr; 
if [myErr != noErr) 
goto bail: 

myErr = QTNevAIiasC&myFile, Stay AliasHandle* true): 
if (myErr != noErr) 
goto bail: 

// create an output from this file 

myErr “ SGNewOutput(gSeqGrabber, (Handle)myAliasHandle, 
rAIiasType. seqGrabToDisk, krnyOutput); 
if (myErr I- noErr) 
goto bail: 

// associate this output with the specified channel 

myErr = SGSetChannelOutput(gSeqGrabber H theChannel, 
myOutput); 

bail: 

free (my Prompt); 
free(myFileName); 

if (myAliasHandle 1“ NULL) 

MspaseHandle((Handle]myAliasHandle); 

return(myErr); 

} 


Keep in mind that we now have three files floating around. 
We have the main output file (set by a call to SGSetDataOutput); 
this file contains the movie atom, which in turn contains two 
track atoms. These track atoms contain references to the two 
channel output files (set by calls to SGSetChannelOutput), The 
channel output files are media files; they cannot be opened by 
QuickTime-savvy applications directly. Instead, they are opened 
only indirectly, whenever the main output file is opened. 


Recording the Captured Data 

So we’ve set the main output file and, if desired, the 
channel output files. It's time to start recording some captured 
data into those files. As indicated earlier, we do this by calling 
SGStartRecord: 

myErr = SGStartRecord[gSeqGrabber): 

Once we’ve successfully called SGStartRecord, the sequence 
grabber will capture sound and video data into the specified 
output file or files until we tell it to stop (by calling SGStop). We 
need to give some processor time to the sequence grabber, just 
as we did during previewing, by calling SGIdle. In QTCapture, 
we’re going to use a fairly cheesy strategy of just recording until 
die user dicks die mouse button: 

while (1Hutton() && [myErr — noErr)) 
myErr = SGIdle(gSeqGrabber); 

SGStop(gSeqGrabber); 
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This strategy 1 has the benefit of simplicity and also of providing 
maximum processing time to the sequence grabber, but it’s 
certainly not appropriate for a real-life capture application. The 
tasks of providing a better user-interface for starting and stopping 
die recording process and of rewriting die code to use the call to 
SGIdle in our idle-event handler QTAppJdle are, as you’ve 
probably guessed, left as exercises to die reader. (Calling Button in 
a while loop is particularly obnoxious when running on Mac OS X; 
see the SGDataProcSampie package cited at die end of this article 
for some sample code that uses Carbon events to call SGIdle.) 

Listing 15 shows our complete recording function, 
QTCap_Record. 

Listin g 15: R ecordin g captured data into a file 

QTOip^ Record 

void QTCap_Record (void) 

I 

FSSpec tnyFile; 

Boolean mylsSelected - false: 

Boolean raylsReplacing = false; 

StringPtr rnyPrompt * 

QTUtlls_ConvertCToFascalStringCkCapSavePrompt); 

StringPtr myFileNatne = 

QTUtils_ConvertCToPascalString(kCapSaveMovieFil.eNariie); 
long myFlags - createMovieFileDontOpenFile | 

createMovieFileDontCreateMovie | 
createMovieFileDontCreateResFile; 
ComponentResuit myErr = noErr: 

// stop everything while the dialogs are up 

SGStop(gSeqGrabber); 

// prompt the user for new file name 
QTF rame_Pu tFile(myPrompt, myFileName, imyFile, 
imylsSelected, SmylsRaplacing): 
myErr = ayIsSelected ? noErr ; userCanceledErr; 

If (myErr != noErr) 
goto bail: 

// delete any existing the movie file, if the user so instructs 
if tmylsReplaeing) 

DeleteMovieFilef&myFile): 

myErr = SGSetDataOutput[gSeqGrabber, &myFile, 
fieqGrabToDisk): 
if (myErr 1" noErr) 
goto bail: 

// ask for separate video and sound track tiles, if requested 
if ((gSoundCbannel 1= NULL) && ^RecordSound && 

(gVideoChannel 1= NULL) gRecordVideo && 
gSplitTracks) ( 

myErr = QTCap_SetTrackFile{gVideoChannel, 

kVideoSaveFroapt, kVideoSaveNovieFileNaroe): 
if (myErr 1= noErr) 
goto bail: 

myErr “ QTCap_SetTrackFiie(gSoundChanneL 

kS out 1 , d Save Prompt, kSoundSaveMovieFileNameJ : 
if (myErr \= noErr) 
goto bail: 


// if not recording sound or video, then disable those channels 
if ((gSoundChannel != NULL) && IgRecordSound) 
SGSetChannelUsago(gSoundChannel t 0); 

if ((gVideoChannel I" NULL) && [ gRecordVideo) 
SGSetChannelUsage(gVideoChannel, 0); 

// attempt to recover tile preview area obscured by dialogs 
#if TARGET_0 S_WIN 3 2 
UpdatePort(^Monitor); 

//end if 

SGUpdate(gSeqGrabber, 0); 


// create a movie file for the destination movie 

myErr = CreateMovieFile(&inyFile. sigMoviePlayer, 
smSystemScript. rayFlags. NULL, NULL); 

if (myErr ) = nolrr) 
goto bail; 

FlushEvents(mDownMask + mUpMask, 0); 

if record until the user clicks the mouse button 

myErr - SGStartReeord(gSeqGrabber); 

if (myErr l- noErr) 
goto bail; 

while (!Button0 && (myErr — noErr)) 
myErr = SGIdle(gSeqGrabber); 

// if we recorded until we ran out tif space, liven allow SGStop to l>e railed to write 
die 

// movie resource; the assumption here is that the data output filled up but the disk 
has 

// enough free space left to write die movie resource 

if (1((myErr = dskFulErr) || [myErr 1" eofErr))) 
goto bail: 

// stop the recording that s currently happening 

myErr = SGStop(gSeqGrabber): 

SGStartPreview(gSeqGrabber); 

bail: 

free(myPrompt); 

free(myFileName); 

if (myErr — noErr) 
return: 

SGPaose(gSeqGrabber p false); 

SGStartFreviewfgSeqGrabber); 

] 

Notice that once weTe done recording, we restart the 
previewing process by calling SGStartPreview. 

Conclusion 

We now know how to use the .sequence grabber and sequence 
grabber channel components Lo preview and capture video and 
sound data from a camera or other audiovisual device attached to 
our computer We’ve seen how to display the settings dialog boxes 
that permit the user to configure die various channels, and we’ve 
also seen how to set the .sound and video channels to capture into 
different output files. And we did all of this without knowing very 
much at all about die various components that do all the tow-level 
work. That’s part of the beauty of die sequence grabber: it gives us 
a simple, high-level interface to a set. of fairly complex operations. 

Saving this captured data in a file is greal stuff, of course, but 
diere are certainly other things we might want to do with it. For 
instance, we might want to send it out ii over a network, so that 
people located remotely can watch and listen to our data. In tire next 
article, we’ll see how QuickTime can help us do that. 

Credits 

Thanks are due to Kevin Marks, who reviewed ihis article 
and provided a number of helpful comments. The code in 
QTCapture is based heavily on an existing sample code package 
called Hack TV. It and several other useful sample code packages 
related to capturing (including the SGDataProcSampie package 
mentioned earlier) are available on-line at 
http://d®eloper apple.com/samplecode/Sample_Code/QuickTi me/ 
Capturing, htim 
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MAC OS X 


By Dan Wood, Alameda CA 


The Tortoise and the Hare 


Why Carbon Developers Should Start 
Learning Cocoa 

We all know the fable about the tortoise and the hare. It 
can be interpreted many ways, but let's say that it's about the 
overconfident rabbit finding himself outpaced by the diligent 
tortoise. 

Having returned from a week at WWDC, I am sad to 
report that there seems to be a tortoise-and-hare situation 
brewing in the Macintosh developer community. 

In spite of the dominance of Windows and despite a 
recent economic slowdown, it was dear by looking at the 
crowds at WWDC that the Macintosh development community 
is alive and kicking. But let's take a look at who is developing 
software For the Macintosh today. First off, you have the old- 
timers, die one who have been programming the Mac since 
the days of black/white screens and floppy disks. These guys 
can patch a trap in their sleep and understand the cosmic 
significance of Tech Note #31- But due to the acquisition of 
NeXT by Apple, there's another group of developers that 
suddenly find themselves with a marketable skill set and a 
potential user base, and they were in force at the conference. 
(After all, the number of copies of Mac OS X sold to date has 
far surpassed the entire NeXT user base!) These weren't the 
only kinds of developers at WWDC — after all, there were 
people who program in pure java and are delighted to see a 
new platform for development and deployment, and there 
was a large WebObjects crowd as well. But on the desktop 
application development space, iL was clear Lhat there were 
two separate species — the Carbon-based life forms and the 
Cocoa-based life forms — and there wasn l any camaraderie 
between them. 

Two Frameworks 

Apple has provided Mac OS X with two first-class 
frameworks for developing applications, Carbon and Cocoa. 


Carbon is an evolution of the procedural APIs for the Mac 
that date back to 1984. It’s the classic way of developing for 
the Mac, with a few twists to make programs run properly 
under Mac OS X as a first-class citizen. Cocoa is the object- 
oriented API for building Mac OS X that comes from 
OpenStep, which itself is descended from NeXTStep. And at 
WWDC, the Cocoa developers were outnumbered by the 
Carbon developers by a pretty big margin. 

Perhaps there's nothing inherently wrong with having 
two first-class APIs for programming a Macintosh. Nothing 
like this has ever succeeded before, though many (especially 
Apple) have tried. In general, an OS has always had a single 
dominant way of programming. Prior to Mac OS X, that 
dominant paradigm has been the Classic Macintosh Toolbox, 
programming in C++, using Metrowerks PowerPlant, So 
what’s tile point of Apple trying to introduce a new 
framework (along with a new language, to boot) for 
development? Why is Apple trying to ruck the boat? Are they 
just setting us developers up for a conflict? 

Think Different 

One thing that Apple has succeeded in doing over the 
last years has been surprising iLs detractors by creating 
amazing products. After the public had written off Apple for 
dead, here comes the iMac, the stylish G3 and G4, the drool- 
inducing Titanium PowerBook, killer apps such as iMovie 
and iTunes s and now an OS that pleases the crowds with 
Aqua and the geeks with its buzzword compliance and 
existing developers with its Carbon transition path 

I ni going to go out on a limb by expressing the opinion 
that Cocoa is just such an amazing product, just one for 
developers. Trouble is. many Macintosh developers are going 
to have to 'Think Different" if they are going to reap the 
benefits. 

I feel qualified to express such an opinion because 1 
straddle both worlds. I’ve been developing for the Mac since 
the screen was 512 pixels across. J ve done my fair share of 


Dan Wtxxi is a long-time Macintosh developer who started learning about Mac OS X technologies immediately after Apple acquired NeXT. He has 
programmed for the Mac using Forth, Pascal, Scheme. 680x0 assembly, C, C++, Java, and Objective-C, using object frameworks such as Think Class 
Library, Metrowerks PowerPlant, Swing, and Cocoa, You can reach him at dwood@kaielta.com. 
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C++; I’ve written Full-sized applications in PowerPlant, and I 
love MacsBug, But shortly after Apple acquired NeXT, I 
started learning Cocoa (or OpenStep or Yellow Box as it was 
called) and l started to, well, think different. IVe since 
written a full-sized application in Cocoa. And frankly, I'm 
now spoiled: 1 don't want to see another line of C++ again. 

A Substantial Investment 

Since 1 still have many friends and acquaintances in the 
“Carbon” camp, I am interested to hear what they think of 
Cocoa. It’s disheartening to hear how few of these folks 
express any desire to learn Cocoa. Some claim that they don’t 
like the syntax of Objective C. Others say that it’s too much 
of a learning curve. But 1 think that for the most part, it’s 
because long-time Mac developers have spent a long time 
investing in the Mac toolbox, and don’t want to see that 
expertise go to waste. 

This makes a great deal of sense. After all, getting to 
know the intricacies of each manager in the Mac toolbox, 
along with the subtleties of C++ (a language that won’t stand 
still), learning and keeping up with PowerPlant, and tracking 
new APIs from Apple, is indeed a lot of effort over the years. 

But perhaps a different approach would be to frame 
one’s expertise as owning a boat. Let’s say you like to race 
sailboats, and you have a boat that you bought 15 years ago. 
Every year you have to sink a substantial amount of money 
into maintaining it, One year, you have to overhaul the 
engine; another year there’s a leak to repair; perhaps the 
navigation system needs replacement, After fifteen years, you 
have a working boat, but you’ve sunk $ 100,000 into that boat 
over its lifetime. Somebody suggests you sell it and get a 
new boat, one that’s faster, more efficient, and less likely to 
need repair, but you're going to resist it. After all, look at 
how much money you've spent on yours! And look at the 
new things you’ll have to learn to pilot and maintain the 
boat! That old boat will do just fine, thank you. 

That kind of thinking may not be rational if you “do the 
math.” But it’s just as hard to let go of emotional investment 
as financial investment. 

I view Cocoa as that new boat that traditional Mac 
developers are being offered. And it’s hard to let go of the 
years of honing your investment. And worst of all, I see a 
great community of Mac developers with “old boats” that are 
so immersed in their decision not to look at the new 
technology called Cocoa that they are going to find 
themselves the hares in the aforementioned fable. 
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Hare vs. Tortoise 

Back lo our Tortoise and Hare allegory. The tortoises, 
who have learned Cocoa — perhaps because they started out 
as NeXT developers, or perhaps because they had an open 
enough mind to try it out — have been quietly sneaking up 
with their shiny new boats made out of Cocoa. We haven’t 
quite reached this point yet, but I believe that the traditional 
Mac developers are going to find themselves “beaten" by the 
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Cocoa developers — not in the sense of a one-on-one race, 
but in the marketplace. Why? Because once you have made 
die initial investment in learning Cocoa, the long and short 
of it is that it's easier and faster to bring products to market. 

Carbon’s advantages over Cocoa 

Analogies are great, but they don't work in real-world 
situations. And in the real world, there are lots of 
applications that need to be brought forward to Mac OS X. 
And Carbon is just the technology for that. Carbon means 
that you don't have to throw away your code base and start 
over. Carbon means you can crank out new versions of your 
application in PowerPlanl, Carbon means you get your 
application finished now instead of later. No learning of new 
languages or frameworks is required. 

Cocoa’s advantages over Carbon 

When you are starting to write any new application, 
however, you have to start designing and programming from 
ground zero. With Cocoa, ground zero is several floors above 
Carbon, Here is my take on why, 

* Already object-oriented. Rather than needing to graft a 
framework such as PowerPlanl over a procedural API 
(while still leaving all the underpinnings fully exposed), 
Cocoa is object-oriented at the most fundamental level. 

* Heterogeneous data types. To represent a simple piece of 
data such as a string using C++ and PowerPlanl and the 
Mac Toolbox, you may have 10 keep track of resources 
and pointers and handles, Pascal strings, null-terminated C 
strings, PowerPlanl classes such as LStr255, C++ string 
objects, and so forth. Converting among all those Lypes is 
half of your work! Cocoa has a string class called NSString. 
Other objects (such as dictionaries, numbers, booleans, 
colors, arbitrary data encapsulation, etc.) all have their 
own classes, and they all lit together in a modular fashion. 
You never have to parse through bits and bytes unless 
you're reading a legacy data structure. Containers of 
objects contain other objects, enabling a complex structure 
can be read or written in a single line of code. 

* Easier language than C++. Learning Java or learning 
Objective C shouldn't be that difficult for an experienced 
developer. And the syntax is so much simpler that you 
can probably get by without a "language lawyer" on staff 
to help you understand the subtle intricacies of C++. To 
quote Tom Cargfl from the C++Journal, “If you think C++ 
is not overly complicated, just what is an abstract virtual 
base pure virtual private destructor, and when was the 
last time you needed one?" 


* More Object-Oriented than C++. While C++ has the 
object-oriented properties of inheritance, polymorphism, 
and encapsulation, what is lacks is dynamism. With 
Objective-C (and, to some extent, Java), you can send an 
arbitrary message to an arbitrary object. The “fragile base 
class” problem of C++ does not exist in Objective C. Most 
of the classes in Cocoa take advantage of Lhis, making it 
very easy build an application. 

* No more “hookup" code. Even with the aid of a C++ 
framework like PowerPlant, much code needs to be 
written to access Lhe user interface from the code (e.g. 
FindPaneByIDO) and to dispatch user input to the code 
via switchO statements. In Cocoa, you hook up the code 
to the UI using Interface Builder, No code is written or 
generated, meaning significantly smaller programs, 

• Flatter Class Hierarchy; Because of the dynamic nature of 
Objective C and the notion of delegation, the class 
hierarchy of Cocoa is extremely flat. Your applications 
rarely need to subclass Cocoa classes. The delegation 
model of Cocoa emphasizes cooperation between classes 
rather than extension of existing classes. By avoiding 
subclassing, your objects avoid having to know about the 
workings of their parent class. 

• Gestalt, No, I'm not talking about an API for querying a 
Mac's capabilities* All of the above reasons combined, 
somehow, make up an experience for the developer that 
is more than just their sum. Simple applications in Cocoa 
are just that — simple. Complex applications are possible 
and surprisingly manageable. 

The Finish Line? 

There is no real finish line; Cocoa and Carbon will 
continue to exist for some time. Each has their advantages, 
but Carbon is the winner when there are business reasons; 
Cocoa is the winner when there are technical reasons. As 
time goes on, the business advantages of Carbon will fade 
away, and the market for Cocoa programmers will be larger 
than the market for Carbon programmers. The developers 
that insist on defending their investment in Carbon avoid 
Cocoa when it comes time to build new projects may find 
that the Cocoa developers have beaten them to market, I 
hope that this doesn't happen. If you are a carbon developer, 
start learning Cocoa in your spare time — Pick up the new 
Learning Cocoa book from O'Reilly and try it out. The 
smartest developers in the w r orld are Mac developers — 
Imagine how much better off we will all be if they can 
leverage Cocoa. Gfrj 
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PYTHON ON 
THE MAC 


By Rob Bedford 


Using Python on the Macintosh 


Introduction to Python and MacPython 


Introduction 

This article is intended as an introduction to the Python 
language on die Mac. While tills will require the introduction of 
the MacPython environment, il is not intended as a review of the 
MacPython environment. Python is an easy to learn language 
that is an excellent tool for making prototypes and quick GUI 
front ends. The Mac implementation also has hooks for Mac 
specific functionality such as Applescript and Quicklime. 
Hopefully this article will lead toward the reader further 
exploring Python, 

Overview 

Python is open source and the license is GPL compatible (as 
is MacPython). MacPython is the Mac implementation of the 
Python language. r lhe package includes an interpreter capable of 
executing text files, an IDE, a GUI toolkit, and droplets to make 
applets or applications. The current version (2.1) is capable of 
running on System 9 or X (native) however the GUI toolkit does 
not run native on X at this time. 

While Python files can be created with any text editor, the 
included IDE provides the ability to execute from the editor and 
access to a debugger in addition to file creation. The error 
reporting from within the IDE also tends to lie more verbose and 
useful than those reported by the interpreter. While not 
necessary on the Mac, files should end in .py for compatibility 
with other operating systems. 

The GUI toolkit is called Tkinter and is a Python 
implementation of Tk. Tk Ls die graphical toolkit created for 
building graphical user interfaces with TCL. While originally for 
TCL, Tk has been ported to Perl and Python also. Although there 
are other GUI toolkits available, Tkinter is the Python standard 
and has excellent support, portability and functionality. Among 
the widgets provided by Tkinter are Entry Field, Menu, Scrollbar, 
Button, Checkbox, Radiobutton, Scale (slider), Listhox, Text, 
Canvas and a variety of Canvas drawing widgets. The toolkit also 


provides three geometry managers grid, pack and place, which 
can be used individually or in combination. The grid manager 
aligns all objects within a grid. The pack manager is similar to 
packing in java with the objects arranging themselves based 
upon window content and shape. The place manager places a 
widget at a precise coordinate. 

WxPython is an alternative GUI toolkit that was not easily 
available at the time this article was written, however indications 
are that it will be available soon. While this toolkit is not as 
accepted for use with Python, ii has some advantages that 
Tkinter does not such as printing support. 

Python can be run as an interactive script or interpreted. To 
run interactively, open the Python interpreter and type the code 
into the provided window. Pressing Enter or Return causes the 
code to execute. To inn Python code in interpreted mode, drag 
and drop the text file unto the Python Interpreter application. 
However if desired an applet can be generated by either 
choosing Save As Applet while in the IDE or dropping the file on 
the BuildApplet droplet. Note that the created applets require that 
Python be installed to run. If a standalone application is desired 
there is a BuildApplication droplet provided for the task. When 
using the BuildApplication droplet if a syntax error is reported and 
the same code executes fine from the IDE and interpreter, be 
sure that the last line is blank (no tabs). This is probably caused 
by the script looking for code due to the indentation. 

Python can be extended using G. This provides a seamless 
interface to native C code for faster execution. 

Language 

Python is an interpreted language that self compiles to byte 
code when possible. Python has good performance for an 
interpreted language but the speed increases after one run since 
all subsequent runs are from compiled byte code. 

Python is fully object oriented (even integers are objects) 
however it can also be used as a sequential language* The syntax 
is Cdike except that there are no end of line markers or braces 
used. The block structure is implemented based entirely upon 


He has worked on a variety of platforms implementing systems from embedded automotive to missile defense. When not coding he is riding his 
motorcycle while trying to find new waterfalls to make QTVR panoramas of. 
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indentation. Thus Python code is formatted into a readable 
structure by necessity. Python comments are indicated by # with 
everything after the # treated as a comment. Multiple lines of 
code cannot he commented in blocks however Python does 
provide a doc string that provides multi-line comments. There 
are tools that extract doc strings to create documentation from 
Python source files. 

Python variables are typeless objects, however while data Ls 
stored there is a type associated with it. Thus a string can be 
stored in a variable then be overwritten with an integer. 

In addition to standard types such as integer, string and real. 
Python defines dictionaries, lists and tuples. Although these 
types at first seem simple these additional types are very 
powerful. One example of the power would be using lists as 
dynamic structures. Also the structure can 1>e extended and since 
the data is further down the list it will not effect most code that 
already exists. 

Lists can contain anything. The elements need not be of the 
same type and can even themselves be lists. An index is used to 
access or change data. Additionally, you can slice sections out of 
them or concatenate them together. Tests for membership and 
length are also available. 

Strings are very similar to lists with the elements containing 
characters. However strings are immutable and thus cannot be 
changed in place. For instance it is possible to add a group of 
characters to a string variable and then reassign a new group of 
characters. However single characters within the string variable 
cannot be altered (immutable). 

Tuples are similar to lists bur tuples are immutable. While 
this seems to be an unnecessary duplication of lists it allows 
const-like operation. 

Dictionaries are collections of data that are accessed by key. 
This provides better performance on large collections of data 
than lists. 


When using Python in an object oriented fashion self provides 
a reference to the referring object. When defining a function in 
Python self must always Ire the first parameter in the argument list. 
When calling a function the self parameter is passed by default. Hie 
Super keyword references the objects parent class. Also when using 
Python as an object oriented language functions whose names begin 

and end in double underscores have special meaning._in it_Ls 

called upon object initialization. _add_and_mul_are used to 

overload + and - respectively. Others are defined and are left to the 
reader to find. 

Python also provides functionality that is associated with 
scripting languages such as the ability to execute external 
applications and regular expressions. 

Starting Python 

Begin by obtaining and installing Python. The official Python 
Language website is http://www.python.org and the official 
MacPython website is http://www.cwi,nl/^ack/imcpytlion,html. 
First go to the Python site and download the documentation for 
Python. Tine documentation is not included in the MacPython 
distribution but is well done and worth the download time (die 
tutorial is highly recommended). Then go to the MacPython site 
and download the full installer 

The documentation expands to nine pdf files: 


Api.pdf 

Python/C API Reference Manual 

Dist.pdf 

Distributing Python Modules 

Doc, pdf 

Documenting Python 

Ext.pdf 

Extending and Embedding the Python 


Interpreter 

Inst.pdf 

Installing Python Modules 

Lib. pdf 

Python Library' Reference 

Mac. pdf 

Macintosh Library' Modules 

Ref. pdf 

Python Reference Manuals 

Tut.pdf 

Python Tutorial 
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Let’s face it: Much of programming is boring 

User 


Apple 
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Interface 


Events 

tool can save days, weeks, or even months 
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Abstract Model 


Model - View-Controller 

AppMaker’s generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates "human, professional quality code” 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete' resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B*0*W«E*R»S 

Development 
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Application 
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The Python Library Reference and Python Reference 
Manuals will be used frequently and are worth converting trees 
to documents. The Python Tutorial is excellent and worth going 
through once. The other documents are useful but can be 
deferred until a higher level of proficiency is achieved. 

Using Python 

To illustrate the use of Python four examples will be 
presented, a simple 1 Icllo World, a GUI Hello World, a droplet 
or application to set the file creator code of text files, and finally 
a demonstration of various Tkinter widgets. 

Hello World 

Here is the traditional Hello World program. Open the 
Python IDE and select New from the File menu. In the new text 
file enter: 

Print 'Hello World' 

Then press the Run All button. Your first Python program 
has just run. 


Graphical Hello World 

But Macs are graphical so next a graphical Hello 
World is next. The first line imports the Tkinter library for 
use. This can also 3>e performed using from Tkinter import 
* which negates die need to use the Tkinter prefix. 
However the longer form was used to illustrate where 
Tkinter widgets are being used. Then Tk is started and 
stored in the variable base. After this we add the Button 
by passing it a container, in this case base, and the text to 
display. After setup is complete we enter the mainloop 
and are done, 

import Tkinter 
base - Tklntet-Tk() 

Tkinter , Button (base , text = 'Hello Worldpack0 
base.mainloop() 


Creator Code Editor 

The following code is for a program to change the 
creator code of the file. The default operation is to read 
from a text file named type_preferences (in the same 
folder as the code) the creator code and type code 
(TEXT 1 ) and set files that are dropped on it to that creator 
code. Files that are not of type ‘TEXT 1 are ignored. Also 
the creator code can he set to the desired application by 
dropping if on the applet. 

The code starts by importing the desired symbols. 
Although the imports are usually placed at the top this is 

not required. Go to the bottom and find if_ name_ == 

1 _main_ r : this rather odd looking construct is very useful. 

If this module is imported into another program this code 
causes the main function to be ignored, however if 
execution begins in this module the check is true and 
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main is executed. This allows each module to be tested in 
a standalone mode and contain test code that does not 
need to be deleted when the module is integrated. The 
main for this program is simple. Main checks the length of 
sys.argv and either creates a CFiletyper object or displays 
instructions to the user. To make this program more useful 
a GUI could be added in place of the display of 
instructions that allows the user to open files or set 
options via the GUI. So what is sys.argv? It is a list that 
contains the name of the applet including its path when 
the applet is double clicked. If items are dropped on the 
applet the name (Including path) of each file is appended 
to the list containing the executing files name. 

Upon creation of the CFiletyper object its_init_ 

routine is called. Now go back to the top of the code and 
examine the class declaration. Take notice of the colon as 
these are the one exception to delimiters and are easy to 

forget. The _init_ function is the standard constructor 

for Python. The first thing the routine checks is for argv 
lists of size two. If the size is two a FileSpec is created to 
store the file's creator and type codes. Notice that creator 
and type codes are assigned in a single statement. If the 
type is l APPU in the file the user has dropped, a file called 
typejDreferences is either opened or created. The new 
creator an type codes are then written to the file and the 
file closed. C programmers will find this code very 
familiar, because Python provides a wrapper for the C file 


routines. For Python experts all the resources needed to 
make extensions are available at the Python websites. 
After the data is written to the file the applet exits back to 
the finder. 

If the type was not ’APPU or the count was higher 
than two, then two routines are called. The first is 
getTypes that tries to open a file named i type_preferences* 
that contains a type code and creator code. If this fails, 
assume the file is missing or corrupted and set the type 
code to ‘TEXT and the creator to Simple Text CttxtO then 
return. After the file is opened the text is stored in the list 
called data with each line becoming an item. The file is 
then closed. Then the data list is parsed, the first 
operation gets the first line and assigns the first four 
characters to self.Creator. The reason for taking only the 
first four characters is to delete the newline character, The 
same operation is then performed on the next item. The 
second function processFiles takes argv and slices off the 
program name creating a new list called fiieList. Then get 
the fileinfo for each file using xstat. The last item in the 
list returned from xstat is the file’s type code. The type is 
checked to ensure it is a TEXT file then set to the creator 
code to new creator code. The next two steps are not 
really necessary but provide the user some feedback by 
telling which files have been changed. 

import sys 
import os 
import mac 
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import maeffi 

class CFUetyper; 
def _inic_(seif): 

*if one item was dropped see if it was an application 

if !en(sys,argv) ™ 2: 

fileSpec = macfs.FSSpec(sys.argv[1]) 
self■Creator, self,Type = 
fileSpec,GetGreatorTypeC) 

if self.Type = *APPL '; 

prefFile = openC*type_preferences*,'w*) 
prefFile. write (self .Creator) 
prefFile. write (*\n‘) 
prefFile.write('TEXT') 
prefFile.close 
else: 

self,getTypes{) 
self,process?lies £) 

^otherwise process files 

else: 

self,getTypes() 
self,processFiles() 

def getType$($dp: 
try: 

prefFile = open('type_preferences‘, 'r‘) 

except: 

self.Type = * TEXT * 
self.Creator ~ 'ttxt' 
return 

data = prefFile,readlines() 
prefFile.close{) 
self.Creator = data[0][:3] 
self,Type ~ data[l][;3] 

def proce s s Files(self): 

fileList = sys.argv[1:3 
for file in fileList: 

fileinfo = mac.xstat(file) 
if fileinfo[-1] ** 'TEXT 1 : 

fileSpec 31 maefs , FSSpec (f lie) 
fileSpec.SetCreatorType[self.Creator. 
self-Type) 

print os.path,split(file)tl] 

print ‘Changing the creator code to Python 

IDE ‘ 

if _name_ ™ *_main_/ : 

if len(sys T argv) > 1: 

CFiletyperO 
else t 

print ‘Drag and drop files onto the applet 1 + 
‘to set creator' 

print ‘Drag and drop application onto the 1 + 
‘applet to set creator* 


Tkinter Demo 

The Tkinter demo is a simple program that has a 
button, checkbutton, radiobutton and scale widget. The 

_main _function starts by initializing Tk and creating a 

Frame to contain the widgets. This frame is then passed 

to the_ init _function of the Test class. Finally the Frame 

is packed with a two-pixel buffer in the x and y direction 
then the main event loop is entered. Note that although 
the baseWin can be packed before creating the Test object 
the best results are always obtained when packing from 
inside to outside. 

The Test class stores the frame passed for later use. 
Then creates a button widget and assigns the clicked 
function to it. The lambda declaration allows s to be 
resolved when the button is clicked and has the benefit 
of stopping the execution of clicked at button creation. 


Lambda is a Python keyword that allows for a function to 
be declared in line. Thus the assignment to command is 
in reality to function pointer that calls sellcltcked. The 
checkbutton is then created and packed followed by a 
call to MakeEntry. MakeEntry then creates a frame to 
contain the Entry field and the accompanying label. 
Finally a radiobutton and scale are created and packed. 

from Tkinter import * 

class Test: 

def_inii_(self super): 

self.super = super 
Button(super, command = 

lambda s “ self : s.clicked(). 
text = 'Hello World').pack() 

Checkbutton (super h text ** 

*A Check Button*).pack() 
self.MakeEntry(super) 

Radiobutton (super, text = 'button l’KpackO 
Scale(super, orient “ 1 horizontal‘).pack() 

def clickedOdf): 

self,super,bell() 

def Make Entry (self, super): 

container ” Frame(super) 

Entry(container) .pack (side - 'right') 
Lfibeltcontainer, text = ‘Enter something:* 
),pack(side = ’left*) 
container.pack() 

if _name,__ — ‘_main,_* : 

base = Tk() 
baseWin = Frame(base) 

Test(baseWin) 

baseWin,pack(padx - 2, pady “ 2) 
base.mainloop{) 


Python Extensions 

There is not enough space in this article to cover all 
of the Python extensions available. However Pmw 
(Python Mega Widgets) will be covered to illustrate the 
installation of an extension and because of the usefulness 
of Pmw for a beginner. 

Pmw is a set of widgets that extend Tkinter, Pmw 
widgets are created in Python primarily for Windows, 
They provide a good example on how Tkinter can be 
extended and are very useful despite some flaws. While 
they work on the Mac the appearance is sometimes less 
than desirable. The notebook widget in particular has a 
terrible appearance that could not be used in a 
deliverable project. 

To install Pmw go to the Vaults of Parnassus (see 
Resources) and download the current version. Once the 
files have been extracted, place the entire directory in the 
Python:Extensions folder. Launch the EditPythonPrefs utility 
and scroll to the bottom. Add S(PYTHON):Extensions;Pmw 
to the list and close the utility. Go to Pmw_Q_8_3:Demos 
and drag and drop All.py to the interpreter, this should 
launch a demonstration of all the Pmw widgets. The same 
result could have been obtained with the utility created in 
the last section and double clicking to execute the code. 
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The Future 

While the current implementation is good the future 
is even brighten Because of the UNIX heritage of X and 
Python, support should only get better 

The exception to this may Tkinter support, if Apple 
were to provide a way to run X windows apps natively 
then Tkinter support would be optimal However if 
Tkinter has to depend on a Tk port to Carbon or Aqua 
then the implementation is subject to more violatility. 
Now for the good news, Python already can run 
native on X, And the event model and other UNIX aspects 
of OS X more closely follow the Python design paradigm 
than does windows. 

Resources 

In addition to the Python Language and MacPython 
site, another site worth visiting is the Vaults of Parnassus 
at http ://www vex, net/parnassus. While this site is not Mac 
specific it contains a w r ide variety of examples and other 
resources that are invaluable, 

* BBEdtt users can obtain a Python plug-in at 
http://homepage,macxom/chnstopherstern. Note that this 
does not work with BBEdit Lite. 

* While the documentation is excellent the following 
books will also be useful. While the Python 
documentation is excellent the Tkinter documentation 


is very poor and the Grayson book highly 
recommended. 

* Learning Python (Help for Programmers), by Mark Lutz 
& David Ascher, March 1999, ISBN 1-56592-464-9 

* Python and Tkinter Programming, by John E Grayson, 
2000, LSBN 1-884777-81~3 

* The Quick Python Book by Daryl Harms and Kenneth 
McDonald, 1999 ISBN 1-884777-74-0 

* While the Learning Python book can be avoided if 
money is tight, the Tkinter book is a necessity. A fair 
portion of the book is dedicated to Pmw but the back 
has the best documentation available for Tkinter. 

* The comp.lang.python newsgroup is also an excellent 
source of help. For Mac specific questions the 
PythonMac SIG is probably a better source though. For 
information on the PythonMac SIG go to the 
MacPython page. 

Conclusion 

Learning Python is both easy and worthwhile. Python is a 
mature language and useful tool for programmers and is suitable 
for projects of all sizes. The interpreted nature of Python allows 
for quick code/test cycles. The byte code compilation of Python 
yields letter speed than traditional scripting languages. The 
community is very helpful and die tools actively supported. 
Python’s UNIX heritage will only make the mac future brighter. 
But most importantly Python is a pleasure to use. 
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The below news headlines recently crossed our news desk* For more information on 
each of these items, check out the MacTcch web site <http://www,macteeh.corn> and 
search out the below headlines from the home page. 


* Master Key 2.0 h More Options for 
Macintosh Manager Netw orks 

■ Watson Released for Mac OS X - With 
Open Architecture 

* Aerux Releases iBui Id 
Lite/Pro/Site/Developer I. i 

* digital forest merges with lnfoasis 

* Carbon Events Plugin 2*0 for REALbasic 

* Package Tracker 3-6 

* Super Get Info 1.0.5 

* Feelorium releases Testation 1,0.1: 
QuickTime text track editor 

* OpenBase SQL 7.0.2 released, cross 
platform features available 

* Direction Finding Kit Available For 
802.11b WLAN Receiver 

* Berkeley Updates WLAN Receiver For 
802.11b Networks 

* eMail Alert! 2.8.5 

* Baker Update Gets Peristent Article 
Queues 

* BJugs List Management Engine 1.1 

* XTension 37-4 

* IOGEAR brings USB 2,0 technology to 
KVM switch 

* WI has released Wing for Mac OS X 

* OpenOSX Ships Gimp 1.2.3 for Mac OS 
X CD 

* Diffusion Effect Updated to v. 2.0 

■ Trinfinity Software releases Skeleton 
Key version 10 

■ Fourth World Releases WebMerge 1.9 

* CDFinder 15 

* Optigold ISP 2,8.7 

* Recosoft Announces VEM: Document 
Converter, ini port/export for OEMs 

* JAW software sliips MPEG2$plitter 1.0,4 
for Mac OS 

* Digital Universe V2.40 

* UtilityX: Mac OS X on Older Macs 

* SuSE Linux 7.3 Now Available for 
PowerPC 

* ASG Announces version 1,6*2 of 
GctltRight 

* Hasten 1.1 Available Now 

* Text Wielder Public Beta: Mac OS X 
Custom Services 

* Exhibitors lining Up To Showcase at 
Macworld Conference Expo 
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* Dr. Bott announces connectivity 
accessories for Apple's iPod 

* Macs Design Studio Releases Web Help 
Desk 5.1 

■ CWCVS 2.4.1: GxleWanrior version 
control plug-in for GNU CVS 

* TECSoft's new Workflow Automation with 
AppleScript Training CD 

* Clean-Install Assistant 1.5.2 Now Available 

* ID3X 2.0 

* CWPrc yjector 3-4,1; S ha rewa re Ve rsion 
Control Plugin 

* Dr. Bott announces the shipping of ADC 
Extension 

* JAW software ships Happy Lasso: Claris 
Home Page Patch 

* SQLBoss 1,0 final release is out 

* iPod For Windows 

* Mac Hack 2002 Dates Announced 

* Balloon Helper 1.0 

* MacTech Magazine Rolls Oul Updated 
Career Site For Mac 

* Java Announces The First Product 
Delivering Profession 

* MacTech Magazine Rolls Oul Updated 
Career Site For Mac 

* Point In Space Announces Filemaker 5.5 
Database Hosting 

* Eridanus Releases Baker TOT 

* Vicomsoft MacOS X Internet Gateway 
Public Beta 

* OpenOSX Office 0,9 Now Shipping 

* ACDSee 4,0 Tops One Million Downloads 
In First Month 

* IntelliMeige L3 released 

* texLSOAP 31 released 

* JobOrder's Internet module is now 
shipping 

* Trinfinity Software releases Seagull Video 
Player version 1.0 

* Power On Ships Now Up-to-Date Sl 
Contact for Mac OS X 

* WestCiv Webware releases version 2.1 of 
Style Master 

* VOODOO Personal 2.1.1 

* Happy Mik for MacOS: PageMill Fateh 

* MacVCD 3-0 Released 

* Fontagent 8,7 Improves Power, Help And 
Performance 

* Carbon Events plugin for REALhasic 
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MACTECH 

ONLINE 


by Jeff elites <online@mactecb.com> 


Emacs 


In our last installment, we talked about ssh, and how 
it could be used in a network-rich world to ease 
administration of remote machines, and do so securely. 
One of the more common things that you'll find yourself 
doing along these lines is editing configuration files or 
other text-based things. What you will need, of course, is 
a text editor A good command-line, terminal-based text 
editor can make all the difference between an easy task 
and an onerous one, especially when working with files 
on a remote system. It may go against the grain of a long¬ 
time Mac user to even touch such a thing, but they are 
indispensable in those situations where they fit the bill, 
and truth be told they can actually be fun (you can keep 
this last part secret if you want). So this month, we are 
going to talk about text editors, and focus on emacs, the 
mother of all text editors. 

Text Editor Choices 

In the command-line world, the choice of text editors 
quickly narrows down to three, or really two. Although 
many others exist, the three that you'll hear about 
universally are vi, emacs, and pico, all of which are 
installed by default with Mac OS X, The last of these, pico, 
is a small (hence the name) text editor—small both in 
memory footprint and in features. It r s simple to use (with 
on-screen Instructions), and its key selling point is that it h s 
available even if you are booted into Mac OS X in single- 
user mode, frustrated and trying to fix something which is 
badly broken and not letting you boot normally. But, if 
you need to fire it up more than once in a blue moon you 
will quickly find yourself wanting more, which brings us 
to our two choices for full-blown, serious text editors. 
Both vi and emacs will let you get your job done, but they 
differ radically in their philosophies: vi tries to be 
minimalist, and emacs throws in every feature including 
the kitchen sink (and every other sink you could think 
of). And, as with all extremes, you can find camps who 
will vehemently defend either The choice comes down to 
a matter of taste, and no one can really convince anyone 
to switch once they have chosen, but why try? Here I’m 
going to talk mainly about emacs, which I chose for very 


simple reasons: vi has separate command and edit modes, 
which confuse me, whereas emacs uses modifier keys for 
commands and leaves plain typing alone, and emacs just 
felt like more fun—it's bloated with features but that gives 
you lots of room to grow as a user. 

Of course, I’m not trying to talk anyone out of using 
ProjectBuilder, TextEdit, BBEdit, or whatever as their 
primary text editor, but 1 am encouraging you to take a 
look at emacs: as a supplement, for specialized tasks, or 
for a change of pace and a new perspective. 

Easing into emacs 

Emacs has as one of its primary goals to be extensible, 
M's written almost entirely in its own flavor of Lisp (elisp, 
or Emacs Lisp), and almost every aspect of it is 
customizable, either through configuration or 
programming (and there’s a fine line between the two, as 
elisp is an interpreted language). There are add-on 
modules to allow you to transfer files via ftp, drive build 
tools and debuggers, interface with version control 
systems, move files around the filesystem, read 
documentation, and even read email, post to Usenet, or 
browse the w r eb. Also, there are distinct modes to ease 
editing of source code of various programming languages 
or markup languages, customizing aspects such as 
keyboard navigation and syntax coloring, 

GNU Emacs 

<http;//www,gnu,org/software/emacs/> 

With such as wealth of features, some users will say, 
* l neatf" 1 and others will ask, ll why?\ and that's pretty much 
what decides whether emacs is the right editor for you. The 
nice thing is that you don’t have to tackle all of the features 
of emacs at once—you can learn just a few to start out, 
and expand as you like. In fact, the only things you really 
need to know to get started are how to save a file, and 
how to quit the application. (You can open a file with 
emacs when you invoke it from the command line, and 
typing and moving around use the same keystrokes as a 
GUT text editor, so these are both as you would naturally 
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guess.) her these bare essentials, things are in fact easier 
than they would be with vi. To get you started, there are 
a couple of convenient reference sheets on the web that 
you can download and print out—one is from 
refcards.com and the other is from Rice University, which 
also has a downloadable tutorial to walk you through the 
basics. (This tutorial, as well as both reference sheets, are 
downloadable in PDF format.) Also, emacs itself has a 
built-in tutorial which will teach you a more extensive set 
of skills. (1 recommend working through the emacs 
tutorial in several sessions, so that you have time to 
absorb it gradually rather than being overwhelmed.) For 
other questions that may come up as you go along, emacs 
has a built-in documentation system, and an FAQ 
(readable within emacs and also available on the web). 



GNU Emacs quick reference card 
<http://www.refcards.com/aboutyemacs.html> 

GNU Emacs Reference Card 

<http://www.rice.edu/Computer/Document5/Unix/unix5.01.pdf> 

Intro to GNU Emaa 

<http://www.rice.edu/Computer/Documents/Unix/unix5.pdf> 

GNU Emacs FAQ 

<http://wwwJerner.co.il/emacs/> 

In addition to the expected features for a text editor, 
emacs has some interesting “basic” features that you’ll 
want to learn almost right away, in particular opening and 
working with multiple files at the same time. Emacs has 
the ability the split up its terminal’Window real estate so 
that you can work with multiple files side-by-side in one 
terminal window. (In emacs parlance these sections are 
called “windows” , but they all live in one real 
Terminal.app window, so don't be thrown off by the 
terminology.) You can also toggle which file is being 
displayed in which “window", so you can have an 
arbitrary number of files open with only one or two 
“windows”, if you like, which can be very useful when 
editing source code. 

Emacs does tend to be all-encompassing, and it has 
been described as being an operating system as much as 
a text editor. In fact, it really can be an entire work 
environment inside of your larger work environment, 
allowing you to use its own features as well as to drive 
external tools, and one recommended usage mode is to 
launch emacs at the start of your work day, do everything 
you need to do without ever leaving emacs, and quit only 
at the end of the day. While this may be possible, there’s 
no reason that you have to use emacs this way—it’s fine 
to use it as little or as much as you like. As you get used 
to using emacs alongside your other tools, and as the 
keyboard-centric nature of emacs grows on you, you'll be 
happy to discover that some of the basic key bindings of 
emacs are also available for use in other applications, 
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including while editing on the command line of tcsh, and 
even within GUI-based editors such as TextEdit and 
ProjectBuiider. 

XEmacs 

Although I’ve been using the term “emacs” genetically, 
there are actually several different flavors of emacs available. 
Mac OS X comes with GNU Emacs already installed, and this 
is arguably the standard emacs in wide use today, and can be 
found on most Linux systems as well. GNU Emacs, 
distributed by the Free Software Foundation, is full-featured, 
and there isn't a pressing reason to go looking for a different 
version, but there is one alternative which is worth looking 
at: XEmacs, Formerly called “Lucid Emacs”, XEmacs 
originated as a branch off of GNU Emacs, mostly stemming 
from differences in philosophy about how emacs should 
evolve, and they are still largely similar to the end user. Don’t 
be confused by the name—although XEmacs can create and 
manage its own GUI under XII, complete with pull-down 
menus and mouse support, it also can also operate within a 
standard terminal window just like GNU Emacs, (In fact, 
GNU Emacs can also take advantage of XII if present, so the 
name “XEmacs" is just misleading,) Take a look at the 
XEmacs site and see if it has any unique features which you 
need. One advantage it has at the moment is that it supports 
the use of color in terminal windows (for things such as 
syntax coloring of source code), although this feature is also 
slated to be included in the next major release of GNU 
Emacs. XEmacs is reported to be fairly straightforward to 
compile under Mac OS X, and it’s also available for 
installation by the Fink package manager—if you haven’t 
heard of Fink, you should definitely check it out; it makes 
installation of lots of standard Unix software a virtual snap. 
(Currently the XEmacs installation used by Fink is configured 
to require XU, which Fink can also install, although a 
configuration which doesn't require XII may become 
available in the future.) 

XEmacs: The next generation of Emacs 

<http://www.xemacs.org/> 

Fink 

<http://f i nk. sou rceforge. net/> 

Further Documentation 

As usual, O'Reilly and Associates is your one-stop 
shopping center for printed references. Learning GNU Emacs 
will give you a firm grounding in all of emacs' basic features, 
as well as a lour of its more advanced features. They also have 
a companion pocket reference, which is great for looking up 
the key commands for things you know you’ve done before 
but can’t quite remember how* It picks up where the 
downloadable reference cards leave off, and also covers a 


slightly newer version of emacs than the Learning GNU Emacs 
book, For advanced users who wish to customize or extend 
emacs, there is Writing GNU Emacs Extensions, which 
introduces elisp and leads you through all the details of bossing 
around emacs, in small or extensive ways. 

Learning GNU Emacs, 2nd Edition 
<http://www.oreiliy.com/catalog/gnu2/> 

GNU Emacs Pocket Reference 
<http://www.oreilly.com/catalog/gnupr/> 

Writing GNU Emacs Extensions 
<http://www.orei! ly,com/cata[og/gnuext/> 

Finally, the Free Software Foundation has the official 
manual for GNU Emacs, as well as documentation on 
Emacs Lisp; you can buy printed copies or download the 
books in a number of different formats from the FSF web 
site. There you 11 also find an interesting paper by Richard 
M. Stallman, open-source icon and original author of GNU 
Emacs, about the design of this versatile text editor. 

GNU Emacs Manual 

<http://www.gnu.org/manual/emacs/index.html> 

Programming in Emacs Lisp 
<http://www.gnu.org/manual/emacs1isp1ntro/> 

EMACS: The Extensible, Customizable Display Editor 
<http://www.gn u ,org/software/emacs/emacs-paper.html> 


emacs Culture 

if you find that emacs isn’t to your liking and you’d 
prefer to use vi, that fine. I don’t mind. Really. But if youTe 
sure about that, you should also take a look at vim (which 
stand for Vi IMproved), which is a version of vi with several 
enhancements added. You can find information and source 
at the VIM 1 lome Page, and you can also install it via the Fink 
package manager mentioned above. (A vanilla vi, specifically 
nvi according to the man page, is Installed with Mac OS X by 
default). If you Ye wavering, check out the essay by Charles 
Sebold, detailing his journey through various text editors, 
and his eventual conversion into an emacs devotee. And if 
you've been Fully converted, cruise on over to 
geekcheat.com for an emacs reference in ihe form of a mug, 
mouse pad, or T-shirt. 

The VIM (Vi IMproved) Home Page 
<http://www.vim.org/> 

Why I became an Lmacs user 
<http://www.messengers“ 0 f- 
messiah.org/~csebold/emacs/why.phtmi> 

Emacs (and vi) merchandise 

<http://www.geekcheat.com/> Mi 
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REALbasic® 


REAL Software and MacTech present the REALbasic Showcase to 
highlight some of the fantastic solutions created by REALbasic users 
worldwide .The showcase illustrates the wide range of applications that 
developers using REALbasic can create. Some benefit any Mac user, and 
others are more specific. All of them are seriously cool! 

REALbasic is the powerful, easy-to-use tool for creating your own 
software for Macintosh, Mac OS X, and Windows. It runs natively on 
Mac OS X as well as earlier versions of the Mac OS. For more 
information, please visit: <www. real basic, com >. 

The Made with REALbasic program is a cooperative effort between 
REALbasic users and REAL Software, Inc. to promote the products 
created using REALbasic and the people who create them. For more 
information about the Made with REALbasic program, please visit: 

<www.realbasic.com/realbasic/mwrb/Partners/MwRbProgram.html>. 








REALBASIC SHOWCASE 


Extend REALbasic with 
Advanced Plugins 


Spreadsheet Controls: 

We provide a wide range of spreadsheet controls for 
REALbasic, including muitistyled and custom rendering 
spreadsheet controls. 
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1 

Stun* text 

More text 

z 

Some text 

Mors text 
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Some text 
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Some text 
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S& 5 

Some lex) 

More text 
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©» 7 
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a 

Some text 
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* More than 32k of rows. 

* Classic, OS X and Win32. 

* Accelerated for maximum 
speed. 

* Images in cells. 
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Cryptography: 

We provide data encryption, encoding, 
compression and hashing for REALbasic, 

Supported Algorithms: 

* Encryption: 

- e-Cryptlt 

- BlowFish (448 bit) 

-AES (Rijndael) (256 bit} 

* Encoding: 

- e-Crypttt Flexible 

- Base 64 

- BinHex 

- MacBlnary III 

- AppleSingle / Double 

- UUCoding 

* Compression: 

- Zip on Strings and streams ( gz) 

* Hashing and Checksums: 

- CRC32 / Adler32 

- MD5/HMAC MD5 

-SHA/SHA1 / HMAC SHA1 


Other Plugins: 

We have many other 
plugins for REALbasic, 
including plugins to do 
advanced MacOS 
Toolbox tasks and more 
custom Controls. 



Speed up developement and make 
more advanced applications 
by using plugins ! Get free demos 
at www.einhugur.com 

Einhugur Software 
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accounting software 


"Easy to set lip, easy to use, 
and excellent support from 
the developer.” 

Five stars on VersionTracker.com 

• account chart 

• address index 
• help facility 

$49-95 

Free 30 -day trial 

h It p: // ho m e page, mac .com / id lew i Id /Coro n a US. hqx 

A best friend for business! 

p.o. box 3164 * newfcerg • Oregon * 97132 
idl ewil dttO m-3c.com 
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■ REALBASIC SHOWCASE 



Advertising helps you build your brand . After all, you 
don 't expect someone tobuy your product if they've 
never heard of you , do you? 

All products/services made with or relatedto REALbasic 
qualify to be a part of our exclusive marketplace section. 

Are you looking for extremely small out of pocket 
advertising that will reach your target audience? 

We bill you for ads monthly as each issue ships L 
Contact our ad sales team today for more details. 

Voice: 805-494-9797 xl 13 * eMaihad sales® mactech.com 



www.mactech.com 
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FontViewer 

FontViewer is a simple but elegant font viewer that allows you to 
preview all fonts in vour fonts folder They can be displayed in 
various sizes and styles with the click of a mouse. FontViewer also 
features the ability to display your fonts in a slideshow, and view 
your fonts in almost every type of environment possible (i.e 
desktop , menus, icons , etc.) 


Creative Box URL: http://www.creativebox.net/ 
Developer e-mail: jason@creativebox.net 



piDock is the must hove navigation and launching utility for 
MocOS. Now you con easily organize , navigate and launch 
files with a simple sweep of the mouse. 

Compatible with OS 8.6 through 10.1 , OSX users can now 
controloption click a folder to navigate lt*s contents . 

http://www.pidog.com • http://www.pidock.com 
_ piDock@pidog.com _ 






iScreensaver 

Designer 

for Macintosh and Windows 



the world's only cross-platform 
screensaver design tool 

• build both Macintosh and Windows screensavers 
with a single click, on whatever system' you are using/ 

* use any QuickTime movie format : 

Macromedia Hash, MPEG, Cinepak, MP3, Midi, AVI, DV Video,,. 

• include a hidden movie that can be unlocked 
with a registration code 

* customize and fully-brand both Installers 
and Screensaver control panels with pictures and text 

* screensavers install without DLLs, extensions, or restarts 


Simple 

WYSIWYG 

editor 

supports 
interactive Hash 
and QuickTime 


consistent 
cross-platform 
user interface 


try before you buy 
fully functional 
online downloads 


http:/ iScreensaver. net 

email ; info @ iScreensaver.net 



the iScreensaver Designer editing environment 


* supported systems, as Of November 2001, indude; 

Macintosh OS S.6 to 9.2, Microsoft Windows 9S/9S/ME, NT4/NTT2G0CJ/XP 
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StimpSoft™, Inc. 

StimpSoft ™ /nc. Makers of /nsane/y 
mediocre software for cafe, dogs , vo/es, 
wo/fabies, mangos, crictefe, and 
peop/e. We puf ffte i/j "Software". 

URL: http://www-stiinpsoft.com 
Email: john@stimpsoff.com 



abDataTools 


db Reporfe is a cross-platform report writing application able to 
extract, format and print data from one of various data sources. 
A multitude of built-in features and expressions make db Reports 
a powerful tool for analyzing data. 

Free demo and more details located at 
http://abDataTools.com 
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Control up to 12 changers (4,800 music CDs) 
Control Any Brand Stereo Receiver 
Play MP3 and other Sound Files 
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Whistle Blower 

Enterprise server monitor and restart utility 
whistleblower, sentman.com 

Connecf to and validate the response from web servers, 
cgi scripts and over 23 other types of servers. 

Send email, pages and perform unattended restarts via 
MasterSwitch or PowerKey. 

Shifts make sure that the person on call when the server 
goes down is the one who gets the page . 

68k, PPC and Carbon 

Web based administration lets you check on and restart 
your servers from anywhere . 

Customize your response to an outage with Apple Script 


email us at whistleblower@sentman.com 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Westford, MA 


Parent-Teacher Conferences 

[f you have children in school, you are familiar with parent- 
teacher conferences. Little Johnny isn’t doing so well in French, or 
Algebra, or perhaps Advanced Calculus if your school has a gifted 
and talented program. Or Sally is doing very well in Subatomic 
Physics, and you"d like to hear her teachers tell you so. 

I was reminded recently of a Challenge suggested by Ernst 
Munter to write code that would help schools schedule these 
conferences. Your Challenge this month is to arrange a set of 
parent-teacher conferences that maximize the parents" 
satisfaction and minimize the amount of time wasted by both 
parents and teachers in between conferences. 

You will be given three data sets to work with for each test 
case. The first, in a file childrenNN.txi (where NN is a number 
from 01 to the number of test cases), will have one line for each 
child in the school, containing the child’s name followed by the 
names of one or two parents. No child will appear on more than 
one line, and there will be no duplicate names of children, A 
sample would be the following: 

Johnny Smith, Donald Smith. Marilyn Waters-Smith 
Sally Jones.Samantha Jones 

The second data set, in a file named teachersNN.txt, maps 
children to their teachers. Each line contains the name of a child, 
followed by the name of one of his/her teachers, followed by a 
number from 0 to 9 indicating the strength of the parents’ desire 
to talk with that teacher, A value of 0 indicates no conference is 
desired, up to a value of 9 indicating the strongest desire for a 
conference. Example lines from this file might be: 

Johnny Smith, Richard Darwin, 3 
Johnny Smith. Rene Descartes, 9 
Johnny Smith, Edgar Allen Poe, 0 
Sally Jones, Rene Descartes, 5 
Sally Jones, Albert Einstein, 9 

The final data set, in a file named schedulesNKtxt, identifies 
which parents are available at which times. The first line in this 
file contains the number N of conference periods available for 
scheduling. All teachers can be available for any or all of the 
periods from L.N, Subsequent lines contain the names of parents, 
along with the first and the last conference period for which they 
will be available. Parents will be available for any period between 
their first and last available periods, inclusive. Each parent whose 
name appears in the children.txt file will appear on one line in the 
schedules.Lxt file. Example lines from this file might be: 

9 

Donald Smith. 1.9 
Samantha Jonas, 4,9 
Marilyn Waters-Sraith T 4,6 

Finally, the number of test cases is provided in a file 
input,txt, with a single line containing the number of test cases: 


15 

Your code needs to produce output that provides the 
matching of parents to teachers. The output (conferencesNN.txt) 
should contain one line for each conference, with the name of 
the teacher first, the name of the parent second, and the 
conference period third. No parent or teacher can be in more 
than one conference during a given period. Both parents of a 
given child can participate in a conference with a teacher if they 
are both available during that period (two lines would be output 
in such a case). One line in such a file might be: 

Richard Darwin,Marilyn Waters-Smith.5 

Finally, your solution needs to produce a log file (log.txt) 
that contains, for each test case, the execution time in 
milliseconds that your solution required to process the test case. 

Once again, the objective is to maximize parents" satisfaction 
with Lhe conference schedule, and to minimize wasted time. The 
Challenge wall be scored based on the number of penally' points 
accumulated by each entry. If a desired conference is not 
accommodated, you will accumulate 1-9 penalty points, 
depending on the strength of the parents' desire for that 
conference as expressed in teachers.txt. If a parent has a gap in 
the conference schedule, where a conference is scheduled 
during periods N and N+2, but not in N+l, you will accumulate 
one penalty point for each unscheduled period in the gap. 
Similar penalty points will accumulate for gaps in the conference 
schedule for teachers. Finally, the penalty will lie increased by 
10% for each second of execution time used by your solution. 

We’re going to make another attempt ro broaden the 
development environments accepted for foe Challenge, despite mixed 
success in the past. Tills will lie a native PowerPC Challenge, using any 
of the following environments: CodeWarrior Pro, REALbasic, 
MetaCard, Revolution, or ProjectBuilder. You may use another 
development environment if 1 can arrange to obtain a copy - email 
progdiallenge@rmctech.com to check before you use something else. 
You can develop for Mac OS 9 or Mac OS X. Your submission should 
provide eveiyting needed to build your application, 

Three Months Ago Winner 

I mentioned above that we have had mixed success in 
experimenting with alternative development environments for 
the Challenge. That was certainly true in the September 
Challenge, where we asked readers to produce Nassi- 
Schneiderman diagrams using the environment of their choice. 
Perhaps because the Challenge focused on diagramming C/C++ 
code, no one submitted an entry using these alternative 
environments. Sadly, no one submitted a C/C++ entry either, so 
we have no winner for the Challenge this month. Remember, you 
can’t win if you don’t play! HQ 
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Install My Insanely Great Application for Mac OS X 
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option Is recomniTndod for most users. Uons will bo instated (d 
the Dock. Power M*c G4 desktop users and UM« users will be 
very hAjjpv with this option. 


j Inirodualon 
license Agreement 
Enter Password 
■ Choose Install Folder 
Dock icons 

u Choose Product Features 


install Features for Users On The Go 

This Is the recommended option for users on the go Pow?r8ouk 

-md 1800k users will be the envy of their coworkers. 

All your Mac are belong to us. 




Install Selected Components 

Not sort whal vou want to Install? Think different. Choose this 
option and pick the individual components to Install. 
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JnstatlAnywhere 


Looking good on Mac OS X is easy with InstallAnywhere! 


Let's face it, first impressions are lasting ones. You don't build 
beautiful applications for Mac OS X only to deliver them with 

yesterday's tired installers. 

Zero G has created a powerful and intuitive installation and 
configuration solution that is true to today s Aqua look and feet. 

InstallAnywhere has complete support for Mae OS X, such as 
authentication, file permissions, and platform specific locations 
including installing icons into the Dock, making it the only 
installer you'll ever need. 


And when you're ready to deploy lo Mac OS Classic, Linux, Solaris, 
AIX, HP-UX, or even <gasp!> Windows, InstallAnywhere is ready 
too - anytime, anywhere, on any platform. 

Software innovators like Adobe, Apple, BEA, Borland, HP, t2, Iona, 
Sun, TIBCG and Xerox already depend on InstallAnywhere for their 
software deployment needs. 

See for yourself why InstallAnywhere, the world’s leading multi¬ 
platform deployment solution, is also the best looking and most 
powerful installer for Mac OS X. 



ZERO G 



InstallAnywhere 


Download a free trial version from http;//www.ZefoG.com/goto/macosx 


& 2001 Zero 3 Software, Inc. instailAnywnert and a ere Iraflemi-la m registered trademarks of Zero C Software, Inc. Mac a a trademark Of Apple Cornu der hie., registered 1 n the U.S 
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Conference & Expo . 



Macworld Conference & Expo 

The Moscone Center 
San Francisco, California 


Conferences January 7-11, 2002 
Expo January 8-11, 2002 


Register Online 

www.macworldexpo.com 

For more information, call toll-free 
1 -800-645-EXPO 


Owned aim MinagsiJ by 


• IDG 

WORLD EXPO 


© 2WJ1 m World E*po Al hgtote reserved 
AH other trademarks contained herein are 
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Register online today using 
Priority Code: A-MTCO 

www.macworldexpo.com 


See hundreds of companies and thousands of products at the #1 event for the Mac universe. 



Macworld Conference & Expo is more than a conference, and more than an exposition. It’s a MUST ATTEND 
staple for the Mac community. Enhance your knowledge, network with peers, personally interact with new 
products and technologies, and finalize your purchase decisions under one roof. 

Personalize your educational experience, by mixing-an-matching conference sessions. 

• Macworld/Users - Learn tips and tricks for your favorite application, how to maximize you digital capabilities, or how to create your own 
digital family history. 

BRAND NEW! 

• Macworld/Power Tools - Immerse yourself for two days with one of the most popular productivity toots for the Mac, 
and take your skill set to its top-level, 

• Macworld/Pro - Participate in sophisticated training for Mac networking, digital video and filmmaking, professional publishing, Mac systems 
administrations and management, and detailed technical presentations that take you inside Mac OS X. 

• IWacBeg innings - Enjoy educational sessions full of tips, techniques and fact-filled training. Learn Mac basics, or about the internet. Learn how 
to set-up and create desktop movies, or how to join and utilize a Macintosh user group. These sessions are open to all registered attendees. 

• Workshops - Make the most out of your show experience by adding a full-day workshop to your educational agenda. 

BRAND NEW! 

■ Birds of a Feather - Network with others that share similar interests, problems and curiosities. These sessions are open 
to alf registered attendees. 


Flagship Sponsors 

Macworld Macworld.com ^MacCentrai 
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Yes, please send me the power-pack ... 


Please bill the following address: 


• Stable 

• Superior 


tTrfiuxs 

PowerPC EDITION 7.3 


SuSE Linux 7.3 
• Secure 


SuSE Linux 7.3 
PowerPC EDITION: 


... because Linux users enjoy the power and stability of SuSE Linux. 

Don't compromise. Company 


SuSE Linux 7.3 - no Limits. 

• Full integration with MOL 
(Mac-On-Linux) 

• Scanning made easy with the 
KDEtool Kooka GGE 

• Protect your data with Soft-RAI DOES 


c Great sound with ALSA 

* Surf safely with the Personal Firewall 

* Professional installation support by 
phone, fax and e-mail 

* etc. 


Last name/Nam-e 


Phone 


Street 


Zi p-code / Posta l- code 

□ 5u5E Linux 7.3 PowerPC EDITION 
$79.95 


SuSE Inc — The Linux Experts 

5S0 Second St 
Oakland - CA 94607 


Order Online Today! http://shop.suse.com/mt 


info@suse.com 


(888) 875-4689 


(510) 628-3381 
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We know what s 
really on your mind. 


Introducing CodeWarrior for Mac OS Version 7.0. 


You want to make the move to Mac* OS X—and you still 
want to serve your Classic Mac customers—but you 
don’t have the time to write multiple applications? Relax. 
CodeWarrior for Mac OS supports both platforms. In 
fact, CodeWarrior for Mac OS Version 7.0 lets you create 
a SINGLE application which runs on Mac OS 8.6, 9.x 


AND Mac OS X. 


Develop for targets: Classic Mac OS, Carbon, 
native Mac OS X, and Java 


Develop on Mac OS 8.6, 9.x and Mac OS X 
platforms 


Build native Mach-0 OS X apps 


PowerPlant C++ framework 


Cross-platform development 


So if you’re making the move to Mac OS X, sink your teeth into the industry’s leading software—CodeWarrior for Mac OS 
For more information, or to order, visit www.metrowerks.com. 


How can I build 
apps that run on 
both Classic Mac 
and OS X? 


CodeWarrior 


Mac OS Development Tools 
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